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

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/dist/models/webhook.d.ts

@@ -1,4 +1,8 @@
 export declare class Webhook {
+    partitionKey: string | null;
+    rowKey: string | null;
+    timestamp?: string | null;
+    eTag?: string | null;
     name: string | null;
     url: string | null;
     instanceGuid: string | null;
@@ -6,4 +10,17 @@ export declare class Webhook {
     contentWorkflowEvents: boolean;
     contentPublishEvents: boolean;
     contentSaveEvents: boolean;
+    secureDeliveryEnabled: boolean;
+    signingSecret: string | null;
+    previousSigningSecret: string | null;
+    secretRolledUtc: string | null;
+    retriesEnabled: boolean;
+    retryCount: number;
+    retrySpeed: "fast" | "standard" | "slow" | null;
+    /**
+     * Set only on a `saveWebhook` response, and only when that save is what minted `signingSecret`
+     * (the first save with `secureDeliveryEnabled` on). Use it to surface the new secret once — it is
+     * never stored on the webhook, so a `getWebhook` response never has it.
+     */
+    signingSecretJustCreated?: boolean;
 }

package/dist/models/webhookHistory.d.ts

@@ -0,0 +1,32 @@
+export declare class WebhookHistory {
+    partitionKey: string | null;
+    rowKey: string | null;
+    queuedDate: string | null;
+    sendDate: string | null;
+    url: string | null;
+    instanceGuid: string | null;
+    contentWorkflowEvent: boolean;
+    contentPublishEvent: boolean;
+    contentSaveEvent: boolean;
+    payload: string | null;
+    httpResponseCode: number | null;
+    success: boolean;
+    responseText: string | null;
+    webhookRowKey: string | null;
+    eventKey: string | null;
+    attemptCount: number;
+    lastAttemptDate: string | null;
+    nextAttemptUtc: string | null;
+    lastError: string | null;
+    /**
+     * Whether the last attempt was sent with Standard Webhooks signature headers, as recorded at send
+     * time. `null` means no record — the delivery has not been attempted yet, or the row predates the
+     * field. This is the fact at delivery time, not the webhook's current `secureDeliveryEnabled`.
+     */
+    signed: boolean | null;
+    /**
+     * Signatures sent in the `webhook-signature` header on the last attempt: 0 unsigned, 1 normally,
+     * 2 during the 24-hour grace window after a secret roll.
+     */
+    signatureKeyCount: number;
+}

package/dist/models/webhookHistory.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookHistory = void 0;
+var WebhookHistory = /** @class */ (function () {
+    function WebhookHistory() {
+    }
+    return WebhookHistory;
+}());
+exports.WebhookHistory = WebhookHistory;

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)