@sixtyninecommerce/admin 0.10.0 → 0.12.0

package/dist/search/index.d.ts

@@ -1,4 +1,4 @@
-import type { Transport } from '@sixtyninecommerce/core';
+import { type Transport } from '@sixtyninecommerce/core';
 import type { Call } from '../types.js';
 /** What `admin.search.entities` searches. */
 export type SearchEntityType = 'PRODUCTS' | 'ORDERS' | 'CUSTOMERS' | 'CONTENT';
@@ -76,6 +76,55 @@ export interface SearchEntitiesOptions extends Call {
 export declare const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
 export declare const SEARCH_ENTITIES_MAX_TAKE = 10;
 export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntities($input: CommandSearchInput!) {\n    searchAcrossEntities(input: $input) {\n      products {\n        id\n        name\n        slug\n        previewUrl\n      }\n      orders {\n        id\n        code\n        state\n        orderPlacedAt\n        totalWithTax\n        currencyCode\n        lifecycleStatus\n      }\n      customers {\n        id\n        firstName\n        lastName\n        emailAddress\n        company\n      }\n      content {\n        id\n        collectionId\n        collectionSlug\n        slug\n        status\n        title\n      }\n      skipped {\n        type\n        reason\n      }\n    }\n  }\n";
+/**
+ * The store's search indexes `search.index` reads, one per kind of record. Each holds the store's
+ * rows of that kind; the products index is the admin catalogue index, not the storefront's.
+ */
+export declare const SEARCH_INDEXES: readonly ["products", "orders", "customers", "facets", "promotions", "customer_groups", "stock_locations", "collections"];
+export type SearchIndex = (typeof SEARCH_INDEXES)[number];
+/** The engine's bound on the clauses of one `search.index` call, `filters` and groups together. */
+export declare const SEARCH_INDEX_MAX_FILTERS = 32;
+export interface SearchIndexInput {
+    /** Full text; `''` matches every row the filters keep. */
+    term: string;
+    /**
+     * Clauses, all of which must hold, each one of exactly these shapes on an attribute the index
+     * lets you filter on: `field = "value"`, `field = true|false`, `field STARTS WITH "value"`,
+     * `field CONTAINS "value"`, `field IN ["a", "b"]`, `field IS EMPTY`. Quote a string value with
+     * {@link escapeSearchFilterValue}: `code STARTS WITH "${escapeSearchFilterValue(prefix)}"`.
+     */
+    filters?: readonly string[];
+    /** Groups of clauses: each group must hold, and holds when ANY of its own clauses does. */
+    filterGroups?: ReadonlyArray<readonly string[]>;
+    /** `field` ascending or `-field` descending, on a field the index sorts by; relevance otherwise. */
+    sort?: string;
+    /** Rows to skip, 0 when omitted. */
+    skip?: number;
+    /** Rows to answer, 25 when omitted. */
+    take?: number;
+}
+/** One hit: the record's id, how well it matched, and the index's copy of it. */
+export interface SearchIndexHit {
+    id: string;
+    /** The search engine's ranking score, 0 to 1: higher is a better match. */
+    score: number;
+    /**
+     * The index's snapshot of the record, as the store may see it: written by a job after the
+     * record's change commits, so it can lag by seconds. Read the record itself for current values.
+     */
+    document: Record<string, unknown>;
+}
+export interface SearchIndexResult {
+    items: SearchIndexHit[];
+    /** Every hit the term and filters match, not only this page's. */
+    total: number;
+}
+export declare const SEARCH_ENTITIES_QUERY = "\n  query SearchIndex($input: EntitySearchInput!) {\n    searchEntities(input: $input) {\n      items {\n        id\n        score\n        document\n      }\n      totalItems\n    }\n  }\n";
+/**
+ * A string value inside a `search.index` filter's double quotes: its backslashes and quotes
+ * escaped, so what a person typed can never close the literal and add a clause.
+ */
+export declare function escapeSearchFilterValue(value: string): string;
 /**
  * One search across the store (spec §7 `search.entities`): products, orders, customers and
  * content items matching a term, in one call.
@@ -94,6 +143,32 @@ export declare const SEARCH_ACROSS_ENTITIES_QUERY = "\n  query SearchAcrossEntit
  * outside 1..{@link SEARCH_ENTITIES_MAX_TAKE}, or an empty `types` list.
  */
 export interface SearchModule {
+    /** @effect read */
     entities(term: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult>;
+    /**
+     * One page of one search index of the store: hits in relevance order (or `sort`'s), each with
+     * the index's copy of the record. Use it to find ids by text or by an indexed attribute the
+     * record's own list cannot filter on, then read the records themselves.
+     *
+     * - **The store is always the one you act on**: no filter reaches another store's rows.
+     * - **Documents are index snapshots**, updated by a job after each change: read the record for
+     *   current values, and expect a just-written record to be missing for a few seconds.
+     * - Needs the read permission of the index's own list: `ReadCatalog` or `ReadProduct` for
+     *   products; `ReadOrder` for orders; `ReadCustomer` for customers; `ReadCustomer` or
+     *   `ReadCustomerGroup` for customer groups; `ReadCatalog`, `ReadProduct` or `ReadFacet` for
+     *   facets; `ReadPromotion`; `ReadCatalog` or `ReadStockLocation`; `ReadCatalog` or
+     *   `ReadCollection`. Without it: `PermissionDeniedError`.
+     * - An app reading customer data below `full` is refused the orders and customers indexes
+     *   (`CUSTOMER_DATA_NOT_GRANTED`): the hits alone would say which customer matches a name.
+     *
+     * Refused: an index not in {@link SEARCH_INDEXES} (`ValidationError` `SEARCH_INPUT_INVALID`, before
+     * anything is asked); and by the engine with `SEARCH_INPUT_INVALID` (400) a clause on an attribute
+     * the index does not filter on or in another syntax, more than {@link SEARCH_INDEX_MAX_FILTERS}
+     * clauses, or a negative `skip`/`take`. A `sort` field the index cannot sort on is ignored.
+     * `SERVICE_UNAVAILABLE` (503, retryable) when the search service did not answer.
+     *
+     * @effect read
+     */
+    index(index: SearchIndex, input: SearchIndexInput, options?: Call): Promise<SearchIndexResult>;
 }
 export declare function createSearchModule(transport: Transport): SearchModule;

package/dist/search/index.js

@@ -1,3 +1,4 @@
+import { ValidationError } from '@sixtyninecommerce/core';
 /** The engine's bounds, as `searchAcrossEntities` documents them. */
 export const SEARCH_ENTITIES_MIN_TERM_LENGTH = 2;
 export const SEARCH_ENTITIES_MAX_TAKE = 10;
@@ -41,6 +42,41 @@ export const SEARCH_ACROSS_ENTITIES_QUERY = /* GraphQL */ `
     }
   }
 `;
+/**
+ * The store's search indexes `search.index` reads, one per kind of record. Each holds the store's
+ * rows of that kind; the products index is the admin catalogue index, not the storefront's.
+ */
+export const SEARCH_INDEXES = [
+    'products',
+    'orders',
+    'customers',
+    'facets',
+    'promotions',
+    'customer_groups',
+    'stock_locations',
+    'collections',
+];
+/** The engine's bound on the clauses of one `search.index` call, `filters` and groups together. */
+export const SEARCH_INDEX_MAX_FILTERS = 32;
+export const SEARCH_ENTITIES_QUERY = /* GraphQL */ `
+  query SearchIndex($input: EntitySearchInput!) {
+    searchEntities(input: $input) {
+      items {
+        id
+        score
+        document
+      }
+      totalItems
+    }
+  }
+`;
+/**
+ * A string value inside a `search.index` filter's double quotes: its backslashes and quotes
+ * escaped, so what a person typed can never close the literal and add a clause.
+ */
+export function escapeSearchFilterValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
 export function createSearchModule(transport) {
     return {
         async entities(term, options = {}) {
@@ -58,5 +94,32 @@ export function createSearchModule(transport) {
             }, call);
             return data.searchAcrossEntities;
         },
+        async index(index, input, options) {
+            if (!SEARCH_INDEXES.includes(index)) {
+                throw new ValidationError({
+                    code: 'SEARCH_INPUT_INVALID',
+                    message: `The search index must be one of ${SEARCH_INDEXES.join(', ')}.`,
+                    status: 400,
+                    service: 'vendure',
+                });
+            }
+            const { term, filters, filterGroups, sort, skip, take } = input;
+            const data = await transport.graphql({
+                api: 'admin',
+                query: SEARCH_ENTITIES_QUERY,
+                variables: {
+                    input: {
+                        term,
+                        entityType: index,
+                        ...(take === undefined ? {} : { take }),
+                        ...(skip === undefined ? {} : { skip }),
+                        ...(sort === undefined || sort === '' ? {} : { sort }),
+                        ...(filters?.length ? { filters: [...filters] } : {}),
+                        ...(filterGroups?.length ? { filterGroups: filterGroups.map((g) => [...g]) } : {}),
+                    },
+                },
+            }, options);
+            return { items: data.searchEntities.items, total: data.searchEntities.totalItems };
+        },
     };
 }

package/dist/seo/config.d.ts

@@ -0,0 +1,128 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { SettingsSourceKind } from '../tenant/settings-sources.js';
+import type { Call } from '../types.js';
+/**
+ * How often the SEO audit (the storefront crawl included) runs. Mirrors `@IsIn` on the plugins
+ * service's `UpdateSeoConfigDto` and the meta catalog's `SEO_CRAWL_SCHEDULES`, pinned by
+ * `__tests__/seo-config.spec.ts`.
+ */
+export declare const SEO_CRAWL_SCHEDULES: readonly ["off", "daily", "weekly"];
+export type SeoCrawlSchedule = (typeof SEO_CRAWL_SCHEDULES)[number];
+/**
+ * The ACTIVE store's SEO automation, as the plugins service applies it. The switches
+ * (`autoRedirectsEnabled`, `indexnowEnabled`, `cruxEnabled`, the crawl settings) are part of the
+ * `settings.seo` group: while the store takes the group from its organization they are the
+ * organization's, and `source` says so. The IndexNow key and the Search Console connection are
+ * always the store's own.
+ *
+ * The keys follow the service's wire names camelised (`indexnow_enabled` → `indexnowEnabled`), as
+ * the meta catalog's `seo` schema publishes them, so a head that renders that schema maps each
+ * property mechanically.
+ */
+export interface SeoConfig {
+    /** Changed URLs are submitted to IndexNow (needs {@link SeoConfig.indexnowKey} to send any). */
+    indexnowEnabled: boolean;
+    /** The store's IndexNow key, served at `/<key>.txt`; null until one is generated. */
+    indexnowKey: string | null;
+    /** The Search Console property the store connected; null when none. */
+    gscPropertyUrl: string | null;
+    /** The store holds a Search Console connection. The credential itself is never answered. */
+    gscConnected: boolean;
+    /** When the connection was made (ISO 8601, UTC); null when there is none. */
+    gscConnectedAt: string | null;
+    /** Core Web Vitals (CrUX). Stored and shown; nothing on the platform reads it yet. */
+    cruxEnabled: boolean;
+    /** A string on the wire: a newer service may answer a schedule this SDK does not name yet. */
+    crawlSchedule: SeoCrawlSchedule | (string & {});
+    /** The most storefront pages one audit crawls (10 to 5,000). */
+    crawlMaxPages: number;
+    /** How fast the audit crawls, in pages per second (1 to 10). */
+    crawlRatePerSec: number;
+    /** A renamed product, collection or page keeps its old URL alive with a redirect. */
+    autoRedirectsEnabled: boolean;
+    /** `organization` while the switches above are the organization's, else `channel`. */
+    source: SettingsSourceKind | (string & {});
+    /** The organization locks `settings.seo`: {@link SeoConfigModule.set} refuses any change. */
+    locked: boolean;
+    /** The store keeps its own switches although the organization shares the group. */
+    overridden: boolean;
+    /** The organization shares the group without locking it, so the store may override it. */
+    inheritable: boolean;
+    /** The store's organization; null for a store outside any organization. */
+    organizationName: string | null;
+}
+/** The switches {@link SeoConfigModule.set} changes; a key left out keeps its value. */
+export interface SeoConfigPatch {
+    indexnowEnabled?: boolean;
+    cruxEnabled?: boolean;
+    crawlSchedule?: SeoCrawlSchedule;
+    /** A whole number from 10 to 5,000. */
+    crawlMaxPages?: number;
+    /** A whole number from 1 to 10. */
+    crawlRatePerSec?: number;
+    autoRedirectsEnabled?: boolean;
+}
+/** What {@link SeoConfigModule.rotateIndexnowKey} answers. */
+export interface IndexnowKeyRotation {
+    /** The new key. The store's `/<key>.txt` serves it from now on; the old key is void. */
+    key: string;
+}
+/**
+ * `admin.seo.config` — the ACTIVE store's SEO automation on the plugins service (Settings → SEO):
+ * automatic redirects, IndexNow, Core Web Vitals and the audit schedule. Needs the store's `seo`
+ * plugin: without it every method is `PermissionDeniedError` (403) naming the plugin.
+ *
+ * The other half of the store's SEO settings, the channel defaults (storefront URL, share and AI
+ * crawler defaults), is `admin.seo.settings`.
+ */
+export interface SeoConfigModule {
+    /**
+     * The automation as the service applies it, and where its switches come from. Needs
+     * `ReadSettings`.
+     *
+     * @effect read
+     * @permission ReadSettings
+     */
+    get(options?: Call): Promise<SeoConfig>;
+    /**
+     * Change the switches `patch` names, and answer the whole configuration as it now applies.
+     * The next audit, URL change or IndexNow submission follows it.
+     *
+     * **Coded refusals:**
+     * - `SEO_CONFIG_INVALID` → `ValidationError` (400), before any request: an empty patch, a
+     *   key that is not a switch here (the IndexNow key and Search Console have doors of their
+     *   own), or a null (no switch can be cleared). One `details[]` entry per key, `field` naming
+     *   it.
+     * - `VALIDATION_FAILED` → `ValidationError` (400), from the service: a value of the wrong type,
+     *   a schedule outside {@link SEO_CRAWL_SCHEDULES}, or a number outside its range.
+     * - `MANAGED_BY_ORGANIZATION` → `BusinessRuleError` (422): a changed switch while the
+     *   organization locks `settings.seo`.
+     * - `ORGANIZATION_SETTINGS_INHERITED` → `BusinessRuleError` (422): a changed switch while the
+     *   store inherits the group; `tenant.settingsSources.override('settings.seo')` first. Sending
+     *   back the values `get` answered is not a change and passes.
+     * - `ORGANIZATION_SETTINGS_SWITCH_OFF_CONFLICT` → `ConflictError` (409): in an organization's
+     *   workspace, while the organization is switching its SEO defaults off and copying them into
+     *   its stores. Nothing changed; try again once that finishes.
+     * - `PermissionDeniedError` (403): the credential lacks `UpdateSettings`.
+     *
+     * @effect write
+     * @permission UpdateSettings
+     */
+    set(patch: SeoConfigPatch, options?: Call): Promise<SeoConfig>;
+    /**
+     * Generate a new IndexNow key for the store and answer it. The old key is void at once: the
+     * store's `/<key>.txt` serves only the new one, and submissions use it from now on. The key is
+     * the store's own, so it is never refused for a store taking `settings.seo` from its
+     * organization.
+     *
+     * **Coded refusals:**
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): the active store is an
+     *   organization's workspace, which has no storefront to prove.
+     * - `PermissionDeniedError` (403): the credential lacks `UpdateSettings`.
+     *
+     * @effect destructive
+     * @permission UpdateSettings
+     */
+    rotateIndexnowKey(options?: Call): Promise<IndexnowKeyRotation>;
+}
+export declare function createSeoConfigModule(transport: Transport): SeoConfigModule;

package/dist/seo/config.js

@@ -0,0 +1,95 @@
+import { ValidationError } from '@sixtyninecommerce/core';
+/**
+ * How often the SEO audit (the storefront crawl included) runs. Mirrors `@IsIn` on the plugins
+ * service's `UpdateSeoConfigDto` and the meta catalog's `SEO_CRAWL_SCHEDULES`, pinned by
+ * `__tests__/seo-config.spec.ts`.
+ */
+export const SEO_CRAWL_SCHEDULES = ['off', 'daily', 'weekly'];
+const INVALID = 'SEO_CONFIG_INVALID';
+const PATCH_KEYS = [
+    'indexnowEnabled',
+    'cruxEnabled',
+    'crawlSchedule',
+    'crawlMaxPages',
+    'crawlRatePerSec',
+    'autoRedirectsEnabled',
+];
+const KNOWN_KEYS = new Set(PATCH_KEYS);
+/** Not a switch: answered by `get`, written through a door of its own. */
+const OWN_DOORS = {
+    indexnowKey: 'indexnowKey is generated by rotateIndexnowKey(), never set.',
+    gscPropertyUrl: 'Search Console is connected through its OAuth flow, never set here.',
+    gscConnected: 'Search Console is connected through its OAuth flow, never set here.',
+    gscConnectedAt: 'Search Console is connected through its OAuth flow, never set here.',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function problemsOf(patch) {
+    const problems = [];
+    const add = (field, message) => problems.push({ field, code: INVALID, message });
+    if (!isRecord(patch)) {
+        add('patch', 'Pass the switches to change as an object, e.g. { autoRedirectsEnabled: false }.');
+        return problems;
+    }
+    const named = Object.keys(patch).filter((key) => patch[key] !== undefined);
+    if (named.length === 0) {
+        add('patch', `Name at least one switch to change: ${PATCH_KEYS.join(', ')}.`);
+    }
+    for (const key of named) {
+        if (!KNOWN_KEYS.has(key)) {
+            add(key, OWN_DOORS[key] ??
+                `${key} is not an SEO automation switch; they are ${PATCH_KEYS.join(', ')}.`);
+        }
+        else if (patch[key] === null) {
+            // The service's validation lets a null through to a NOT NULL column, whose refusal names
+            // no field (the meta catalog's `SEO_NULL`); nothing here has a "cleared" state.
+            add(key, `${key} cannot be cleared; send a value, or leave it out to keep it.`);
+        }
+    }
+    return problems;
+}
+/**
+ * The camelised wire body, its source fields filled in: they came with #882, and a service from
+ * before it leaves them out, which is the store's own settings. Every other field is the
+ * service's, as answered.
+ */
+function configOf(body) {
+    return {
+        ...body,
+        source: body.source ?? 'channel',
+        locked: body.locked === true,
+        overridden: body.overridden === true,
+        inheritable: body.inheritable === true,
+        organizationName: body.organizationName ?? null,
+    };
+}
+export function createSeoConfigModule(transport) {
+    return {
+        async get(options) {
+            return configOf(await transport.rest('plugins', { method: 'GET', path: '/seo/config' }, options));
+        },
+        async set(patch, options) {
+            const problems = problemsOf(patch);
+            if (problems.length > 0) {
+                throw new ValidationError({
+                    code: INVALID,
+                    message: problems.map((problem) => problem.message).join(' '),
+                    status: 400,
+                    service: 'plugins',
+                    details: problems,
+                });
+            }
+            // Only the named switches go out. The transport snake-cases them, and every key here
+            // camelises from a wire name, so the round trip is exact (`indexnowEnabled` →
+            // `indexnow_enabled`); a key spelt any other way would be refused whole by the service.
+            const body = {};
+            for (const key of PATCH_KEYS) {
+                if (patch[key] !== undefined)
+                    body[key] = patch[key];
+            }
+            return configOf(await transport.rest('plugins', { method: 'PUT', path: '/seo/config', body }, options));
+        },
+        rotateIndexnowKey(options) {
+            return transport.rest('plugins', { method: 'POST', path: '/seo/config/indexnow-key/rotate' }, options);
+        },
+    };
+}

package/dist/seo/redirects.d.ts

@@ -18,10 +18,135 @@ export interface RedirectCreateInput {
     statusCode?: number;
 }
 export type RedirectUpdateInput = Partial<RedirectCreateInput>;
+/**
+ * The most rows one {@link RedirectsModule.import} takes. Mirrors `ArrayMaxSize` on the plugins
+ * service's `ImportRedirectsDto` (`services/plugins/src/redirects/dto/import-redirects.dto.ts`),
+ * pinned by `__tests__/redirects.spec.ts`. Change both sides together.
+ */
+export declare const REDIRECT_IMPORT_MAX_ROWS = 5000;
+/**
+ * How long an import may take before the call gives up, unless the caller says otherwise: the
+ * service saves the rows one by one, and a full batch takes far longer than a single write.
+ */
+export declare const REDIRECT_IMPORT_TIMEOUT_MS = 60000;
+/**
+ * One row of {@link RedirectsModule.import}. Not checked before sending: the service judges each
+ * row on its own and reports a bad one in {@link RedirectImportResult.rejected}, so a malformed
+ * row never costs the rest of the batch.
+ */
+export interface RedirectImportRow {
+    /** One exact path, e.g. `/product/old-slug`. */
+    oldPath: string;
+    /** A path, or an absolute `https://` URL. */
+    newPath: string;
+    /** 301 (the default), 302, 303, 307 or 308. */
+    statusCode?: number;
+}
+/** A row the service refused, and why. The other rows still landed. */
+export interface RedirectImportRejection {
+    /** The row's position in the array sent, from 0. */
+    index: number;
+    /** The row's source path as sent. */
+    oldPath: string;
+    /**
+     * The service's sentence for the person fixing the file: a source that is not one exact path,
+     * a destination that is neither a path nor an `https://` URL, a status code outside the five,
+     * a source that redirects to itself, or a row that would close a redirect loop or a chain past
+     * the hop limit (with the rows already stored or with an earlier row of the same batch). There
+     * is no code per row yet.
+     */
+    message: string;
+}
+/**
+ * What an import did. A row whose source the store already redirects UPDATES that redirect
+ * (same source, so never a duplicate); any other accepted row creates one.
+ */
+export interface RedirectImportResult {
+    created: number;
+    updated: number;
+    /** Empty when every row landed. */
+    rejected: RedirectImportRejection[];
+}
+/**
+ * `admin.seo.redirects` — the ACTIVE store's URL redirects, on the plugins service. Storefronts read
+ * the same rows live from the public redirect map (`@sixtyninecommerce/client/next`'s
+ * `createRedirectMiddleware`), so a write here changes what the store's old URLs answer within a
+ * few minutes, with no deployment.
+ *
+ * Every method needs `UpdateChannel` (`FORBIDDEN` → `PermissionDeniedError`, 403, otherwise). The
+ * writes that set up a redirect (`create`, `update`, `import`) are refused in an organization's
+ * workspace with `ORGANIZATION_WORKSPACE_NOT_A_STORE` (`BusinessRuleError`, 422): a workspace has
+ * no storefront. Removing one is never refused there.
+ */
 export interface RedirectsModule {
+    /**
+     * The store's redirects, newest first, a page at a time (`limit` 1 to 200; 50 by default).
+     * Iterate the page (`for await`) to walk every page.
+     *
+     * @effect read
+     * @permission UpdateChannel
+     */
     list(options?: ListOptions): Promise<Page<Redirect>>;
+    /**
+     * Add one redirect. The service applies the same path rules as `import`: a malformed path, a
+     * self-redirect or a status code outside the five is `ValidationError` (400); a source the store
+     * already redirects, a loop, or a chain past the service's hop limit is `ConflictError` (409).
+     * The idempotency key is honoured: a repeat answers the first response.
+     *
+     * @effect write
+     * @permission UpdateChannel
+     */
     create(input: RedirectCreateInput, options?: Call): Promise<Redirect>;
+    /**
+     * Change the fields `input` names; at least one. The same rules as `create`; an unknown id is
+     * `NotFoundError` (404).
+     *
+     * @effect write
+     * @permission UpdateChannel
+     */
     update(id: string, input: RedirectUpdateInput, options?: Call): Promise<Redirect>;
+    /**
+     * Remove one redirect: the old URL stops redirecting once the storefront's copy of the map
+     * expires. An unknown id is `NotFoundError` (404).
+     *
+     * @effect destructive
+     * @permission UpdateChannel
+     */
     delete(id: string, options?: Call): Promise<void>;
+    /**
+     * Add or update up to {@link REDIRECT_IMPORT_MAX_ROWS} redirects in one call, matched on the
+     * source path (a source the store already redirects is updated, never duplicated). Each row is
+     * judged on its own: a bad one is answered in `rejected` by its index and the rest still land.
+     * Rows are applied in order, so a later row may build on an earlier one, and a loop split
+     * across two rows is refused on the second.
+     *
+     * Not atomic and not deduplicated by an idempotency key, but safe to repeat: sending the same
+     * rows again updates them to what they already are.
+     *
+     * **Coded refusals:**
+     * - `REDIRECT_IMPORT_INVALID` → `ValidationError` (400), before any request: `rows` is not an
+     *   array of 1 to {@link REDIRECT_IMPORT_MAX_ROWS} entries. Send a larger file in chunks.
+     * - `ORGANIZATION_WORKSPACE_NOT_A_STORE` → `BusinessRuleError` (422): the active store is an
+     *   organization's workspace.
+     * - `FORBIDDEN` → `PermissionDeniedError` (403): the credential lacks `UpdateChannel`.
+     *
+     * Waits up to {@link REDIRECT_IMPORT_TIMEOUT_MS}, longer than the client's default deadline. A
+     * timed-out import may still have landed (the service keeps saving): list the redirects, or
+     * send the same rows again, which is safe.
+     *
+     * @effect write
+     * @permission UpdateChannel
+     */
+    import(rows: readonly RedirectImportRow[], options?: Call): Promise<RedirectImportResult>;
+    /**
+     * The store's redirects as two Nginx `map` blocks (text: `$redirect_uri` and
+     * `$redirect_status`, keyed on `$uri`), for a site that is not on the storefront SDK: include
+     * it in the server config and redirect on the mapped values. One entry per source path, those
+     * a storefront cannot serve included.
+     *
+     * @effect read
+     * @permission UpdateChannel
+     */
+    exportNginx(options?: Call): Promise<string>;
 }
 export declare function createRedirectsModule(transport: Transport): RedirectsModule;

package/dist/seo/redirects.js

@@ -1,4 +1,25 @@
-import { createPage, readRestPage } from '@sixtyninecommerce/core';
+import { createPage, readRestPage, ValidationError, } from '@sixtyninecommerce/core';
+/**
+ * The most rows one {@link RedirectsModule.import} takes. Mirrors `ArrayMaxSize` on the plugins
+ * service's `ImportRedirectsDto` (`services/plugins/src/redirects/dto/import-redirects.dto.ts`),
+ * pinned by `__tests__/redirects.spec.ts`. Change both sides together.
+ */
+export const REDIRECT_IMPORT_MAX_ROWS = 5000;
+/**
+ * How long an import may take before the call gives up, unless the caller says otherwise: the
+ * service saves the rows one by one, and a full batch takes far longer than a single write.
+ */
+export const REDIRECT_IMPORT_TIMEOUT_MS = 60_000;
+const IMPORT_INVALID = 'REDIRECT_IMPORT_INVALID';
+/** The import's answer, read defensively: an older service may leave `rejected` out. */
+function importResultOf(body) {
+    const record = (typeof body === 'object' && body !== null ? body : {});
+    const count = (value) => (typeof value === 'number' ? value : 0);
+    const rejected = Array.isArray(record.rejected)
+        ? record.rejected
+        : [];
+    return { created: count(record.created), updated: count(record.updated), rejected };
+}
 export function createRedirectsModule(transport) {
     async function list(options) {
         // `GET /redirects` answers with a bare array unless the request OPTS IN.
@@ -33,5 +54,43 @@ export function createRedirectsModule(transport) {
             // discards the body rather than pretending it is a Redirect.
             await transport.rest('plugins', { method: 'DELETE', path: `/redirects/${encodeURIComponent(id)}`, expect: 'void' }, options);
         },
+        async import(rows, options) {
+            if (!Array.isArray(rows) || rows.length === 0 || rows.length > REDIRECT_IMPORT_MAX_ROWS) {
+                throw new ValidationError({
+                    code: IMPORT_INVALID,
+                    message: `Send 1 to ${String(REDIRECT_IMPORT_MAX_ROWS)} redirects per import; split a larger file into several calls.`,
+                    status: 400,
+                    service: 'plugins',
+                    details: [
+                        {
+                            field: 'rows',
+                            code: IMPORT_INVALID,
+                            message: Array.isArray(rows)
+                                ? `${String(rows.length)} rows sent.`
+                                : 'rows is not an array.',
+                        },
+                    ],
+                });
+            }
+            const body = await transport.rest('plugins', {
+                method: 'POST',
+                path: '/redirects/import',
+                // Only the three row fields go out: the service's DTO refuses any other key, which
+                // would fail the whole batch rather than the one row.
+                body: {
+                    redirects: rows.map((row) => ({
+                        oldPath: row.oldPath,
+                        newPath: row.newPath,
+                        ...(row.statusCode === undefined ? {} : { statusCode: row.statusCode }),
+                    })),
+                },
+            }, { timeoutMs: REDIRECT_IMPORT_TIMEOUT_MS, ...options });
+            return importResultOf(body);
+        },
+        async exportNginx(options) {
+            // A text body, never JSON: `blob` keeps the transport from parsing or case-converting it.
+            const answer = await transport.rest('plugins', { method: 'GET', path: '/redirects/nginx', expect: 'blob' }, options);
+            return answer.blob.text();
+        },
     };
 }