@agility/management-sdk 0.1.40 → 0.2.0-beta.2

package/README.md

@@ -15,7 +15,7 @@
 ## About the Management API SDK
 
 - Provides a facility to developers to use the new Agility Management API more effectively.
-- Provides methods to perform operations on Assets, Batches, Containers, Content, Models, Pages, and Users.
+- Provides methods to perform operations on Assets, Batches, Containers, Content, Models, Pages, and Users, and to search an instance.
 - **Content and Page Creation** - Create individual or multiple content items and pages (which automatically get added to batches).
 - **Essential batch workflow operations** - Perform publish, unpublish, approve, decline, and request approval operations on existing batches.
 - Ability to generate Content in bulk for a Website.
@@ -145,6 +145,10 @@ console.log('Content retrieved:', contentItem.fields.title);
 - **[PageMethods](./docs/page-methods.md)** - Page management operations (18 functions)
   - [getPage](./docs/page-methods.md#getpage), [getPageByPath](./docs/page-methods.md#getpagebypath), [getPageHistory](./docs/page-methods.md#getpagehistory), [getPageComments](./docs/page-methods.md#getpagecomments), [getPageList](./docs/page-methods.md#getpagelist), [getPageListByPageTemplateID](./docs/page-methods.md#getpagelistbypagetemplateid), [getPageListByPage](./docs/page-methods.md#getpagelistbypage), [getPageListByPageAndPageTemplateID](./docs/page-methods.md#getpagelistbypageandpagetemplateid), [getPageTree](./docs/page-methods.md#getpagetree), [getPageTemplateList](./docs/page-methods.md#getpagetemplatelist), [getPageSecurity](./docs/page-methods.md#getpagesecurity), [getPageItemTemplateList](./docs/page-methods.md#getpageitemtemplatelist), [getPageContentZones](./docs/page-methods.md#getpagecontentzones), [savePage](./docs/page-methods.md#savepage), [savePageSecurity](./docs/page-methods.md#savepagesecurity), [movePageItem](./docs/page-methods.md#movepageitem), [deletePage](./docs/page-methods.md#deletepage), [batchWorkflowPages](./docs/page-methods.md#batchworkflowpages)
 
+### Search
+- **[SearchMethods](./docs/search-methods.md)** - Search everything in an instance (1 function)
+  - [search](./docs/search-methods.md#search)
+
 ### User Management
 - **[InstanceMethods](./docs/instance-methods.md)** - Instance-level operations (2 functions)
   - [getLocales](./docs/instance-methods.md#getlocales), [getFetchApiStatus](./docs/instance-methods.md#getfetchapistatus)

package/dist/apiClient.d.ts

@@ -9,6 +9,7 @@ import { Options } from "./models/options";
 import { ServerUserMethods } from "./apiMethods/serverUserMethods";
 import { WebhookMethods } from "./apiMethods/webhookMethods";
 import { InstanceMethods } from "./apiMethods/instanceMethods";
+import { SearchMethods } from "./apiMethods/searchMethods";
 export declare class ApiClient {
     _options: Options;
     contentMethods: ContentMethods;
@@ -19,6 +20,7 @@ export declare class ApiClient {
     instanceMethods: InstanceMethods;
     modelMethods: ModelMethods;
     pageMethods: PageMethods;
+    searchMethods: SearchMethods;
     serverUserMethods: ServerUserMethods;
     webhookMethods: WebhookMethods;
     constructor(options: Options);

package/dist/apiClient.js

@@ -11,6 +11,7 @@ var pageMethods_1 = require("./apiMethods/pageMethods");
 var serverUserMethods_1 = require("./apiMethods/serverUserMethods");
 var webhookMethods_1 = require("./apiMethods/webhookMethods");
 var instanceMethods_1 = require("./apiMethods/instanceMethods");
+var searchMethods_1 = require("./apiMethods/searchMethods");
 var ApiClient = /** @class */ (function () {
     function ApiClient(options) {
         this._options = options;
@@ -22,6 +23,7 @@ var ApiClient = /** @class */ (function () {
         this.instanceMethods = new instanceMethods_1.InstanceMethods(this._options);
         this.modelMethods = new modelMethods_1.ModelMethods(this._options);
         this.pageMethods = new pageMethods_1.PageMethods(this._options);
+        this.searchMethods = new searchMethods_1.SearchMethods(this._options);
         this.serverUserMethods = new serverUserMethods_1.ServerUserMethods(this._options);
         this.webhookMethods = new webhookMethods_1.WebhookMethods(this._options);
     }

package/dist/apiMethods/searchMethods.d.ts

@@ -0,0 +1,16 @@
+import { Options } from "../models/options";
+import { SearchRequest, SearchResult } from "../models/search";
+import { ClientInstance } from "./clientInstance";
+export declare class SearchMethods {
+    _options: Options;
+    _clientInstance: ClientInstance;
+    constructor(options: Options);
+    /**
+     * Search everything in an instance: content items, components, pages, assets, models and containers.
+     * Makes one request and never retries.
+     *
+     * Throws `SearchNotAvailableException` when search is not available for the instance yet (HTTP 501),
+     * and `Exception` otherwise, for example with `statusCode` 400 for a blank query or an unknown kind or state.
+     */
+    search(guid: string, request: SearchRequest): Promise<SearchResult>;
+}

package/dist/apiMethods/searchMethods.js

@@ -0,0 +1,81 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchMethods = void 0;
+var exception_1 = require("../models/exception");
+var searchNotAvailableException_1 = require("../models/searchNotAvailableException");
+var clientInstance_1 = require("./clientInstance");
+var SearchMethods = /** @class */ (function () {
+    function SearchMethods(options) {
+        this._options = options;
+        this._clientInstance = new clientInstance_1.ClientInstance(this._options);
+    }
+    /**
+     * Search everything in an instance: content items, components, pages, assets, models and containers.
+     * Makes one request and never retries.
+     *
+     * Throws `SearchNotAvailableException` when search is not available for the instance yet (HTTP 501),
+     * and `Exception` otherwise, for example with `statusCode` 400 for a blank query or an unknown kind or state.
+     */
+    SearchMethods.prototype.search = function (guid, request) {
+        return __awaiter(this, void 0, void 0, function () {
+            var apiPath, resp, err_1;
+            var _a;
+            return __generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        apiPath = "search";
+                        return [4 /*yield*/, this._clientInstance.executePost(apiPath, guid, this._options.token, request)];
+                    case 1:
+                        resp = _b.sent();
+                        return [2 /*return*/, resp.data];
+                    case 2:
+                        err_1 = _b.sent();
+                        if (((_a = err_1 === null || err_1 === void 0 ? void 0 : err_1.response) === null || _a === void 0 ? void 0 : _a.status) === 501) {
+                            throw new searchNotAvailableException_1.SearchNotAvailableException("Unable to search the instance.", err_1);
+                        }
+                        throw new exception_1.Exception("Unable to search the instance.", err_1);
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return SearchMethods;
+}());
+exports.SearchMethods = SearchMethods;

package/dist/index.d.ts

@@ -14,7 +14,10 @@ export * from "./models/media";
 export * from "./models/model";
 export * from "./models/notification";
 export * from "./models/pageItem";
+export * from "./models/geo";
 export * from "./models/pagedResult";
+export * from "./models/search";
+export * from "./models/searchNotAvailableException";
 export * from "./models/sitemap";
 export * from "./models/webhook";
 export * from "./models/webhookHistory";

package/dist/index.js

@@ -30,7 +30,10 @@ __exportStar(require("./models/media"), exports);
 __exportStar(require("./models/model"), exports);
 __exportStar(require("./models/notification"), exports);
 __exportStar(require("./models/pageItem"), exports);
+__exportStar(require("./models/geo"), exports);
 __exportStar(require("./models/pagedResult"), exports);
+__exportStar(require("./models/search"), exports);
+__exportStar(require("./models/searchNotAvailableException"), exports);
 __exportStar(require("./models/sitemap"), exports);
 __exportStar(require("./models/webhook"), exports);
 __exportStar(require("./models/webhookHistory"), exports);

package/dist/models/contentItem.d.ts

@@ -1,3 +1,4 @@
+import { GeoProperties } from "./geo";
 export declare class ContentItem {
     contentID: number;
     properties: ContentItemProperties;
@@ -5,6 +6,17 @@ export declare class ContentItem {
         [key: string]: any;
     };
     seo: SeoProperties | null;
+    /**
+     * GEO / AEO properties of the page this item generates. Only items in a list that backs a
+     * dynamic page carry them. On save, three states:
+     * - left out (`undefined`): everything stored is kept;
+     * - `null`: the whole block is cleared;
+     * - an object: each property in it is applied (a property set to `null` clears just that
+     *   property, one left out is kept; see `GeoProperties`).
+     *
+     * Absent from responses when the item has no GEO data.
+     */
+    geo?: GeoProperties | null;
     scripts: ContentScripts | null;
 }
 export declare class ContentItemProperties {
@@ -24,6 +36,20 @@ export declare class SeoProperties {
     metaHTML: string | null;
     menuVisible: boolean | null;
     sitemapVisible: boolean | null;
+    /** The page's `<title>`, when it differs from the page title. */
+    title?: string | null;
+    /** The page's canonical URL override. */
+    canonicalUrl?: string | null;
+    /** The page's robots directives. */
+    robots?: SeoRobots | null;
+    /** The page's social share (Open Graph) image: an absolute http(s) URL or a site-relative path. */
+    ogImage?: string | null;
+}
+export declare class SeoRobots {
+    /** Whether search engines may index the page. */
+    index?: boolean | null;
+    /** Whether search engines may follow the page's links. */
+    follow?: boolean | null;
 }
 export declare class ContentScripts {
     top: string | null;

package/dist/models/contentItem.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ContentList = exports.ContentScripts = exports.SeoProperties = exports.ContentItemProperties = exports.ContentItem = void 0;
+exports.ContentList = exports.ContentScripts = exports.SeoRobots = exports.SeoProperties = exports.ContentItemProperties = exports.ContentItem = void 0;
 var ContentItem = /** @class */ (function () {
     function ContentItem() {
     }
@@ -19,6 +19,12 @@ var SeoProperties = /** @class */ (function () {
     return SeoProperties;
 }());
 exports.SeoProperties = SeoProperties;
+var SeoRobots = /** @class */ (function () {
+    function SeoRobots() {
+    }
+    return SeoRobots;
+}());
+exports.SeoRobots = SeoRobots;
 var ContentScripts = /** @class */ (function () {
     function ContentScripts() {
     }

package/dist/models/geo.d.ts

@@ -0,0 +1,38 @@
+/**
+ * GEO / AEO (generative and answer engine optimization) properties of a page, or of a content item
+ * in a list that backs a dynamic page (`ContentItem.geo`, the item's own values).
+ *
+ * Writes are three-state, per property:
+ * - property left out (`undefined`), or the whole `geo` left out: the stored value is kept;
+ * - property set to `null`: the stored value is cleared;
+ * - property set to a value: the stored value is replaced.
+ *
+ * To clear the whole block, save the page with `geo: null`.
+ *
+ * `JSON.stringify` drops `undefined`, so a page read with `getPage` (or an item read with
+ * `getContentItem`), changed elsewhere and saved keeps its GEO data. Only set a property to `null`
+ * when you mean to clear it.
+ * Responses leave out properties that aren't set.
+ */
+export declare class GeoProperties {
+    /** The schema.org page type. Defaults to `WebPage` when not set. */
+    schemaType?: GeoSchemaType | null;
+    /** A short, answer-first plain-text summary of the page. */
+    summary?: string | null;
+    /** Editor-supplied JSON-LD (an object, which may hold an `@graph`, or an array of objects). Must be valid JSON. */
+    structuredData?: {
+        [key: string]: any;
+    } | {
+        [key: string]: any;
+    }[] | null;
+    /** The page's AI-engine settings. */
+    ai?: GeoAiProperties | null;
+}
+/** The schema.org page types a page can declare. */
+export type GeoSchemaType = "WebPage" | "AboutPage" | "ContactPage" | "CollectionPage" | "FAQPage" | "ItemPage" | "ProfilePage" | (string & {});
+export declare class GeoAiProperties {
+    /** Whether the page is listed in llms.txt: `inherit` (follow sitemap visibility), `include` or `exclude`. */
+    llmsInclude?: "inherit" | "include" | "exclude" | null;
+    /** Whether AI crawlers may crawl the page: `inherit` (follow the site policy) or `block`. */
+    crawl?: "inherit" | "block" | null;
+}

package/dist/models/geo.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoAiProperties = exports.GeoProperties = void 0;
+/**
+ * GEO / AEO (generative and answer engine optimization) properties of a page, or of a content item
+ * in a list that backs a dynamic page (`ContentItem.geo`, the item's own values).
+ *
+ * Writes are three-state, per property:
+ * - property left out (`undefined`), or the whole `geo` left out: the stored value is kept;
+ * - property set to `null`: the stored value is cleared;
+ * - property set to a value: the stored value is replaced.
+ *
+ * To clear the whole block, save the page with `geo: null`.
+ *
+ * `JSON.stringify` drops `undefined`, so a page read with `getPage` (or an item read with
+ * `getContentItem`), changed elsewhere and saved keeps its GEO data. Only set a property to `null`
+ * when you mean to clear it.
+ * Responses leave out properties that aren't set.
+ */
+var GeoProperties = /** @class */ (function () {
+    function GeoProperties() {
+    }
+    return GeoProperties;
+}());
+exports.GeoProperties = GeoProperties;
+var GeoAiProperties = /** @class */ (function () {
+    function GeoAiProperties() {
+    }
+    return GeoAiProperties;
+}());
+exports.GeoAiProperties = GeoAiProperties;

package/dist/models/pageItem.d.ts

@@ -1,4 +1,5 @@
 import { SeoProperties } from "./contentItem";
+import { GeoProperties } from "./geo";
 export declare class PageItem {
     pageID: number | null;
     name: string | null;
@@ -12,6 +13,16 @@ export declare class PageItem {
     excludeFromOutputCache: boolean | null;
     visible: PageVisible | null;
     seo: SeoProperties | null;
+    /**
+     * GEO / AEO properties. On save, three states:
+     * - left out (`undefined`): everything stored is kept;
+     * - `null`: the whole block is cleared;
+     * - an object: each property in it is applied (a property set to `null` clears just that
+     *   property, one left out is kept; see `GeoProperties`).
+     *
+     * Absent from responses when the page has no GEO data.
+     */
+    geo?: GeoProperties | null;
     scripts: PageScripts | null;
     dynamic: PageDynamic | null;
     properties: PageItemProperties | null;

package/dist/models/search.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A search across everything in an instance: content items, components, pages, assets, models and
+ * containers. Only `query` is required.
+ *
+ * Results are limited to what the caller may see: content, pages and containers for everyone,
+ * components and models with Develop or Manage, assets with Edit or Delete. Content and pages in
+ * containers or pages the caller can't read are left out.
+ */
+export declare class SearchRequest {
+    /**
+     * The text to search for. Words match as prefixes ("newsl" finds "newsletter") and every word must
+     * match; text in double quotes matches as an exact phrase. A number also matches content, page,
+     * asset and model IDs exactly. A blank query is rejected (HTTP 400).
+     */
+    query: string;
+    /**
+     * The kinds of result to return. Defaults to every kind the caller may see. An unknown kind is
+     * rejected (HTTP 400). The facet counts always cover every kind the caller may see, whatever this is.
+     */
+    kinds?: SearchKind[] | null;
+    /** Only search content, components and pages in this locale (for example `en-us`). Omit it, or pass `*`, for every locale. */
+    locale?: string | null;
+    /** Only return content in these containers, by reference name. Limits the search to content kinds. */
+    containers?: string[] | null;
+    /** Only return content and components of these models, by reference name. Limits the search to content kinds. */
+    models?: string[] | null;
+    /** Only return content in this state. An unknown state is rejected (HTTP 400). Limits the search to content kinds. */
+    state?: SearchState | null;
+    /** Only return results modified on or after this date (an ISO 8601 string, or a `Date`). */
+    modifiedAfter?: string | Date | null;
+    /** Results to skip, for paging. Defaults to 0. */
+    skip?: number | null;
+    /** Results to return. Defaults to 25; the API clamps it to 1..100. */
+    take?: number | null;
+}
+/** A kind of search result. */
+export type SearchKind = "content" | "component" | "page" | "asset" | "model" | "container" | (string & {});
+/** A content state to filter on. `any` is the same as leaving it out. */
+export type SearchState = "staging" | "published" | "unpublished" | "any";
+/** The result of a search. */
+export declare class SearchResult {
+    /** The query as it was searched. */
+    query: string | null;
+    /** True when nothing matched every word, so the results match ANY of the words instead. */
+    relaxed: boolean;
+    /**
+     * How many results there are of each kind the caller may see, keyed by kind, whichever kinds were
+     * requested. So it can drive tabs.
+     */
+    facets: {
+        [kind: string]: SearchFacet;
+    } | null;
+    /** How many results there are across the requested kinds. */
+    total: number;
+    /** The requested page of results, best match first. */
+    hits: SearchHit[] | null;
+    /** How far behind the search index is. */
+    indexing?: SearchIndexing | null;
+}
+/** The number of results of one kind. */
+export declare class SearchFacet {
+    count: number;
+    /** True when there are more results than were counted; show the count as a minimum ("N+"). */
+    capped: boolean;
+}
+/** How far behind the search index is. */
+export declare class SearchIndexing {
+    /** Changes not yet searchable. Usually 0; high after a big import. */
+    pending: number;
+    /** True while the instance is being indexed in the background: search again shortly. */
+    catchingUp: boolean;
+}
+/** One search result. Properties that don't apply to the result's kind are null or left out. */
+export declare class SearchHit {
+    kind: SearchKind | null;
+    /** Content Item, List Item, Component, Page, Asset, Content Model, Component Model, Content List or Single Item. */
+    typeLabel?: string | null;
+    /** The result's display name. */
+    name?: string | null;
+    /** Where the result lives: its container, page path, folder or model reference name. */
+    context?: string | null;
+    /** The matching text, HTML-encoded, with each matched word wrapped in `<mark>`. */
+    snippet?: string | null;
+    /** Which fields matched: field names, or `_title`, `_id`, `_attachment`, `_file`, `_model`, `_container`. */
+    matchedFields?: string[] | null;
+    /** The relevance score the results are ordered by. Higher is better. */
+    score: number;
+    /** The locale of a content, component or page result. Null for assets and models. */
+    languageCode?: string | null;
+    /** The state of a content, component or page result (Staging, Published, ...). */
+    state?: string | null;
+    modifiedDate?: string | null;
+    modifiedBy?: string | null;
+    /** A path to open the result in the Content Manager, relative to the instance (for example `content/list-12/listitem-34`). */
+    viewLink?: string | null;
+    /** The content ID of a content item, component or page's content. */
+    contentID?: number | null;
+    /** The ID of the container a content item or component lives in. */
+    containerID?: number | null;
+    containerReferenceName?: string | null;
+    /** The page ID of a page, or of a page a component sits on. */
+    pageID?: number | null;
+    pagePath?: string | null;
+    channel?: string | null;
+    mediaID?: number | null;
+    /** The asset's URL. */
+    url?: string | null;
+    /** The asset's MIME type. */
+    contentType?: string | null;
+    /** The asset's size in bytes. */
+    size?: number | null;
+    modelID?: number | null;
+    modelReferenceName?: string | null;
+}

package/dist/models/search.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchHit = exports.SearchIndexing = exports.SearchFacet = exports.SearchResult = exports.SearchRequest = void 0;
+/**
+ * A search across everything in an instance: content items, components, pages, assets, models and
+ * containers. Only `query` is required.
+ *
+ * Results are limited to what the caller may see: content, pages and containers for everyone,
+ * components and models with Develop or Manage, assets with Edit or Delete. Content and pages in
+ * containers or pages the caller can't read are left out.
+ */
+var SearchRequest = /** @class */ (function () {
+    function SearchRequest() {
+    }
+    return SearchRequest;
+}());
+exports.SearchRequest = SearchRequest;
+/** The result of a search. */
+var SearchResult = /** @class */ (function () {
+    function SearchResult() {
+    }
+    return SearchResult;
+}());
+exports.SearchResult = SearchResult;
+/** The number of results of one kind. */
+var SearchFacet = /** @class */ (function () {
+    function SearchFacet() {
+    }
+    return SearchFacet;
+}());
+exports.SearchFacet = SearchFacet;
+/** How far behind the search index is. */
+var SearchIndexing = /** @class */ (function () {
+    function SearchIndexing() {
+    }
+    return SearchIndexing;
+}());
+exports.SearchIndexing = SearchIndexing;
+/** One search result. Properties that don't apply to the result's kind are null or left out. */
+var SearchHit = /** @class */ (function () {
+    function SearchHit() {
+    }
+    return SearchHit;
+}());
+exports.SearchHit = SearchHit;

package/dist/models/searchNotAvailableException.d.ts

@@ -0,0 +1,12 @@
+import { Exception } from "./exception";
+/**
+ * Thrown by `searchMethods.search` when the API answers 501: search is not available for this
+ * instance yet. It isn't a transient failure, so don't retry it; fall back to listing or filtering
+ * content instead.
+ *
+ * Check with `err instanceof SearchNotAvailableException`, or `err.name === "SearchNotAvailableException"`
+ * when more than one copy of the SDK may be loaded. `statusCode` is 501.
+ */
+export declare class SearchNotAvailableException extends Exception {
+    constructor(message: string, inner?: Error);
+}

package/dist/models/searchNotAvailableException.js

@@ -0,0 +1,41 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SearchNotAvailableException = void 0;
+var exception_1 = require("./exception");
+/**
+ * Thrown by `searchMethods.search` when the API answers 501: search is not available for this
+ * instance yet. It isn't a transient failure, so don't retry it; fall back to listing or filtering
+ * content instead.
+ *
+ * Check with `err instanceof SearchNotAvailableException`, or `err.name === "SearchNotAvailableException"`
+ * when more than one copy of the SDK may be loaded. `statusCode` is 501.
+ */
+var SearchNotAvailableException = /** @class */ (function (_super) {
+    __extends(SearchNotAvailableException, _super);
+    function SearchNotAvailableException(message, inner) {
+        var _this = _super.call(this, message, inner) || this;
+        // The SDK compiles to ES5, where a subclass of Error loses its prototype; restore it so
+        // `instanceof SearchNotAvailableException` works.
+        Object.setPrototypeOf(_this, SearchNotAvailableException.prototype);
+        _this.name = "SearchNotAvailableException";
+        _this.statusCode = 501;
+        return _this;
+    }
+    return SearchNotAvailableException;
+}(exception_1.Exception));
+exports.SearchNotAvailableException = SearchNotAvailableException;

package/docs/content-methods.md

@@ -337,6 +337,16 @@ const contentItems = [
 const savedIds = await client.contentMethods.saveContentItems(contentItems, 'your-guid', 'en-us');
 ```
 
+### GEO / AEO on dynamic page list items
+
+An item in a list that backs a dynamic page can carry a top-level `geo` object (`schemaType`, `summary`, `structuredData`, `ai`), the same shape as a page's `geo` (see [savePage](./page-methods.md#savepage)). `saveContentItem` and `saveContentItems` send it as given, with the same three states: leave `geo` (or a property in it) out to keep what's stored, set a property to `null` to clear it, send `geo: null` to clear the whole block. Items in other lists don't carry `geo`, and `getContentItem` leaves it out when the item has none.
+
+```typescript
+const item = await client.contentMethods.getContentItem(123, 'your-guid', 'en-us');
+item.geo = { ...item.geo, summary: 'The post in one sentence.', ai: { crawl: 'block' } };
+await client.contentMethods.saveContentItem(item, 'your-guid', 'en-us');
+```
+
 ---
 
 ## getContentItems

package/docs/page-methods.md

@@ -525,6 +525,38 @@ console.log('Batch created with ID:', batchId);
 **Error Handling:**
 - Throws `Exception` when validation fails or save operation fails
 
+**GEO / AEO and the extra SEO properties:**
+
+A page can carry a top-level `geo` object (`schemaType`, `summary`, `structuredData`, `ai`) and four more `seo` properties (`title`, `canonicalUrl`, `robots`, `ogImage`). On save, each of these properties has three states:
+
+| In the object you save | Effect |
+|---|---|
+| Property left out (`undefined`), or the whole `geo` left out | The stored value is kept |
+| `geo: null` | The whole `geo` block is cleared |
+| Property set to `null` | The stored value is cleared |
+| Property set to a value | The stored value is replaced |
+
+`savePage` sends the object as JSON, and `JSON.stringify` drops `undefined`, so a read-modify-save that doesn't touch these properties keeps them. Don't set them to `null` unless you mean to clear them. Responses leave out any property that isn't set.
+
+```typescript
+const page = await apiClient.pageMethods.getPage(123, guid, locale);
+page.geo = {
+    ...page.geo,
+    schemaType: 'AboutPage',
+    summary: 'Who we are, in two sentences.',
+    structuredData: { '@context': 'https://schema.org', '@type': 'Organization', name: 'Example' },
+    ai: { llmsInclude: 'include' }
+};
+page.seo = { ...page.seo, title: 'About us | Example', robots: { index: true, follow: true } };
+await apiClient.pageMethods.savePage(page, guid, locale);
+
+// Clear the summary only; everything else in geo is kept
+await apiClient.pageMethods.savePage({ ...page, geo: { summary: null } }, guid, locale);
+
+// Clear all of geo
+await apiClient.pageMethods.savePage({ ...page, geo: null }, guid, locale);
+```
+
 ### savePageSecurity
 
 Updates security settings for a specific page.

package/docs/search-methods.md

@@ -0,0 +1,129 @@
+# Agility CMS & Management API TypeScript SDK
+
+## SearchMethods
+
+This class searches everything in an instance in one call: content items, components, pages, assets, models and containers. Results are ranked across kinds, best match first, and come with a count per kind so they can drive tabs.
+
+**Important Notes:**
+- Words match as prefixes (`newsl` finds `newsletter`) and every word must match; text in double quotes matches as an exact phrase. A number also matches content, page, asset and model IDs exactly
+- If nothing matches every word, the results match **any** of the words instead and `relaxed` is `true`
+- You only see what your permissions allow: content, pages and containers for everyone; components and models need Develop or Manage; assets need Edit or Delete; content and pages in containers or pages you can't read are left out. The API applies this, so there's nothing to filter on the client
+- Changes are searchable a few seconds after they are saved
+- Search is not yet available on every instance. When it isn't, `search` throws a [`SearchNotAvailableException`](#searchnotavailableexception)
+
+### Function List
+- [search](#search) - Searches an instance
+
+### Reference
+- [The SearchRequest object](#the-searchrequest-object)
+- [The SearchResult object](#the-searchresult-object)
+- [SearchNotAvailableException](#searchnotavailableexception)
+
+---
+
+### search
+
+Searches an instance. Makes one request and never retries.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `guid` | `string` | Yes | Current website GUID |
+| `request` | `SearchRequest` | Yes | What to search for, and optional filters and paging. Only `query` is required |
+
+**Returns:** `Promise<SearchResult>`
+
+**Usage Example:**
+```typescript
+import * as mgmtApi from '@agility/management-sdk';
+
+const result = await apiClient.searchMethods.search(guid, { query: 'newsletter' });
+
+console.log(`${result.total} results${result.relaxed ? ' (matching any word)' : ''}`);
+for (const [kind, facet] of Object.entries(result.facets ?? {})) {
+    console.log(`${kind}: ${facet.count}${facet.capped ? '+' : ''}`);
+}
+result.hits?.forEach(hit => {
+    console.log(`[${hit.typeLabel}] ${hit.name} in ${hit.context} -> ${hit.viewLink}`);
+});
+
+// Only published content and pages in en-us, second page of 10
+const page2 = await apiClient.searchMethods.search(guid, {
+    query: '"spring sale"',
+    kinds: ['content', 'page'],
+    locale: 'en-us',
+    state: 'published',
+    skip: 10,
+    take: 10
+});
+```
+
+**Error Handling:**
+- Throws `SearchNotAvailableException` (`statusCode` 501) when search is not available for the instance yet
+- Throws `Exception` with `statusCode` 400 for a blank query, an unknown kind or an unknown state
+- Throws `Exception` when the search fails for any other reason
+
+---
+
+### The SearchRequest object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `query` | `string` | **Required.** The text to search for |
+| `kinds` | `SearchKind[]` | Any of `content`, `component`, `page`, `asset`, `model`, `container`. Defaults to every kind you can see. The facet counts always cover every kind you can see, whatever this is |
+| `locale` | `string` | Only search content, components and pages in this locale (for example `en-us`). Omit it, or pass `*`, for every locale |
+| `containers` | `string[]` | Only return content in these containers, by reference name. Limits the search to content kinds |
+| `models` | `string[]` | Only return content and components of these models, by reference name. Limits the search to content kinds |
+| `state` | `SearchState` | `staging`, `published`, `unpublished` or `any`. Limits the search to content kinds |
+| `modifiedAfter` | `string \| Date` | Only return results modified on or after this date |
+| `skip` | `number` | Results to skip, for paging (default: 0) |
+| `take` | `number` | Results to return (default: 25, at most 100) |
+
+### The SearchResult object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `query` | `string` | The query as it was searched |
+| `relaxed` | `boolean` | `true` when nothing matched every word, so the results match any of the words |
+| `facets` | `{ [kind: string]: SearchFacet }` | `{ count, capped }` for each kind you can see, whichever kinds you asked for. When `capped` is `true` there are more than `count`: show it as "N+" |
+| `total` | `number` | How many results there are across the requested kinds |
+| `hits` | `SearchHit[]` | The requested page of results, best match first |
+| `indexing` | `SearchIndexing` | `{ pending, catchingUp }`: `pending` is the number of changes not yet searchable (usually 0, high after a big import); `catchingUp` is `true` while the instance is being indexed in the background, so search again shortly |
+
+Each `SearchHit` has a `kind`, `typeLabel`, `name`, `context` (its container, page path, folder or model reference name), `snippet` (HTML-encoded, with matched words wrapped in `<mark>`), `matchedFields`, `score`, and a `viewLink` to open it in the Content Manager, relative to the instance. The IDs and details that apply to its kind are set too: `contentID`, `containerID`, `containerReferenceName`, `pageID`, `pagePath`, `channel`, `languageCode`, `state`, `modifiedDate`, `modifiedBy`, `mediaID`, `url`, `contentType`, `size`, `modelID` and `modelReferenceName`. The rest are `null` or left out.
+
+### SearchNotAvailableException
+
+Thrown when the API answers 501: search is not available for this instance yet. It isn't a transient failure, so don't retry it.
+
+```typescript
+import { SearchNotAvailableException } from '@agility/management-sdk';
+
+try {
+    const result = await apiClient.searchMethods.search(guid, { query: 'newsletter' });
+} catch (err) {
+    if (err instanceof SearchNotAvailableException) {
+        // Fall back to listing or filtering content instead.
+    } else {
+        throw err;
+    }
+}
+```
+
+When more than one copy of the SDK may be loaded, check `err.name === 'SearchNotAvailableException'` instead. `err.statusCode` is `501`.
+
+---
+
+## Navigation
+- [← Back to Main Documentation](../README.md)
+- [Authentication & Setup](./auth.md)
+- [AssetMethods](./asset-methods.md)
+- [BatchMethods](./batch-methods.md)
+- [ContainerMethods](./container-methods.md)
+- [ContentMethods](./content-methods.md)
+- [InstanceMethods](./instance-methods.md)
+- [InstanceUserMethods](./instance-user-methods.md)
+- [ModelMethods](./model-methods.md)
+- [PageMethods](./page-methods.md)
+- **SearchMethods** *(current)*
+- [ServerUserMethods](./server-user-methods.md)
+- [WebhookMethods](./webhook-methods.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agility/management-sdk",
-  "version": "0.1.40",
+  "version": "0.2.0-beta.2",
   "description": "Agility CMS Tyescript SDK for Management API.",
   "repository": {
     "type": "git",
@@ -15,7 +15,7 @@
     "clean": "git clean -Xf && rm -rf ./dist",
     "build": "tsc",
     "prepare": "yarn build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "tsc && node --test 'test/**/*.test.js'"
   },
   "keywords": [
     "typescript",