@zachariaz/strapi-plugin-experience-context 0.1.0-dev.0 → 0.1.0-dev.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -41,7 +41,15 @@ Hidden, plugin-owned types: `annotation` (concepts of a page or block), `variati
41
41
 
42
42
  ## MCP tools (the only write path)
43
43
 
44
- `experience_describe_target`, `experience_list_registry`, `experience_list_content_variants`, `experience_create_content_variant`, `experience_update_content_variant`, `experience_associate_variant_with_audience`, `experience_set_experiment`, `experience_associate_variant_with_experiment`, `experience_conclude_experiment`, `experience_annotate_content_with_concepts`, `experience_validate_mapping`, `experience_explain_variant_resolution`, `experience_remove_mapping`, `experience_backfill_block_keys`.
44
+ `experience_describe_target`, `experience_list_registry`, `experience_list_content_variants`, `experience_list_changes`, `experience_create_content_variant`, `experience_update_content_variant`, `experience_associate_variant_with_audience`, `experience_set_experiment`, `experience_associate_variant_with_experiment`, `experience_conclude_experiment`, `experience_annotate_content_with_concepts`, `experience_validate_mapping`, `experience_explain_variant_resolution`, `experience_remove_mapping`, `experience_backfill_block_keys`.
45
+
46
+ `experience_list_content_variants` lists this plugin's block variations (which `zone.*` block a section shows per audience or experiment outcome). Per-entry content variants (one entry, other copy per segment) come from the content-variants plugin (`variants_list_entry_variants`).
47
+
48
+ `experience_list_changes` reads the change log (`experience_changes`), newest first: action, entity, page, section, variation, block, experiment, actor, source, reason, `correlationId` and the before/after records. Filters: page (`targetUid`, `targetDocumentId`, `locale`), `sectionKey`, `variantKey`, `blockKey`, `experimentKey`, `entity`, `action`, `actor`, `source`, `correlationId`, `since`/`until`; paging with `limit` (max 200) and `beforeId`. Needs only the read permission. Example, everything one orchestration run changed:
49
+
50
+ ```json
51
+ { "name": "experience_list_changes", "arguments": { "correlationId": "story-home-hero-3-audiences", "includeValues": false } }
52
+ ```
45
53
 
46
54
  ## Permissions (RBAC)
47
55
 
@@ -1859,6 +1859,64 @@ async function listContentVariants(strapi, args) {
1859
1859
  }));
1860
1860
  return { count: rows.length, targets };
1861
1861
  }
1862
+ const CHANGE_FILTERS = ["sectionKey", "variantKey", "blockKey", "experimentKey", "entity", "action", "actor", "source", "correlationId"];
1863
+ const MAX_CHANGES = 200;
1864
+ const isoOrThrow = (value, name) => {
1865
+ if (value === void 0) return void 0;
1866
+ if (Number.isNaN(Date.parse(value))) throw new ToolError(`${name} must be an ISO 8601 date-time, e.g. "2026-11-18T00:00:00Z".`);
1867
+ return new Date(value).toISOString();
1868
+ };
1869
+ async function listChanges(strapi, args) {
1870
+ const filters = {};
1871
+ if (args.targetUid) {
1872
+ const target = await resolveTarget(strapi, args.targetUid, args.targetDocumentId);
1873
+ filters.targetUid = target.uid;
1874
+ filters.targetDocumentId = target.documentId;
1875
+ } else if (args.targetDocumentId) {
1876
+ throw new ToolError("targetDocumentId needs targetUid.");
1877
+ }
1878
+ if (args.locale !== void 0) filters.targetLocale = args.locale === null ? { $null: true } : args.locale;
1879
+ for (const key of CHANGE_FILTERS) {
1880
+ if (args[key] !== void 0 && args[key] !== "") filters[key] = args[key];
1881
+ }
1882
+ const since = isoOrThrow(args.since, "since");
1883
+ const until = isoOrThrow(args.until, "until");
1884
+ if (since || until) filters.createdAt = { ...since ? { $gte: since } : {}, ...until ? { $lte: until } : {} };
1885
+ if (args.beforeId !== void 0) filters.id = { $lt: args.beforeId };
1886
+ const limit = Math.min(Math.max(Math.trunc(args.limit ?? 50), 1), MAX_CHANGES);
1887
+ const rows = await strapi.documents(CHANGE_UID).findMany({
1888
+ filters,
1889
+ sort: [{ createdAt: "desc" }, { id: "desc" }],
1890
+ pagination: { limit: limit + 1 }
1891
+ });
1892
+ const page = rows.slice(0, limit);
1893
+ const values = args.includeValues !== false;
1894
+ return {
1895
+ count: page.length,
1896
+ hasMore: rows.length > limit,
1897
+ nextBeforeId: rows.length > limit ? page[page.length - 1].id : null,
1898
+ changes: page.map((r) => ({
1899
+ id: r.id,
1900
+ at: r.createdAt,
1901
+ action: r.action,
1902
+ entity: r.entity,
1903
+ entityDocumentId: r.entityDocumentId ?? null,
1904
+ targetUid: r.targetUid ?? null,
1905
+ targetDocumentId: r.targetDocumentId ?? null,
1906
+ locale: r.targetLocale ?? null,
1907
+ sectionKey: r.sectionKey ?? null,
1908
+ variantKey: r.variantKey ?? null,
1909
+ blockKey: r.blockKey ?? null,
1910
+ componentUid: r.componentUid ?? null,
1911
+ experimentKey: r.experimentKey ?? null,
1912
+ actor: r.actor ?? null,
1913
+ source: r.source,
1914
+ reason: r.reason ?? null,
1915
+ correlationId: r.correlationId ?? null,
1916
+ ...values ? { before: r.before ?? null, after: r.after ?? null } : {}
1917
+ }))
1918
+ };
1919
+ }
1862
1920
  async function validateMapping(strapi, args) {
1863
1921
  const s = store$1(strapi);
1864
1922
  const vctx = await validationContext(strapi);
@@ -2509,7 +2567,7 @@ const EXPERIENCE_TOOLS = [
2509
2567
  {
2510
2568
  name: "experience_list_content_variants",
2511
2569
  title: "Experience: list sections and variations",
2512
- description: "Sections and their variations for one page, or across pages filtered by audience id, experiment key or section key. Inactive and orphaned mappings are left out unless includeInactive is true.",
2570
+ description: "Sections and their variations (which zone.* block a page shows per audience or experiment outcome) for one page, or across pages filtered by audience id, experiment key or section key. Inactive and orphaned mappings are left out unless includeInactive is true. Per-entry content variants (one entry, other copy per segment) belong to the content-variants plugin: variants_list_entry_variants.",
2513
2571
  auth: read,
2514
2572
  telemetry: telemetry("list_content_variants"),
2515
2573
  resolveInputSchema: () => utils.z.object({
@@ -2524,6 +2582,34 @@ const EXPERIENCE_TOOLS = [
2524
2582
  resolveOutputSchema: () => loose({ count: utils.z.number(), targets: utils.z.array(loose()) }),
2525
2583
  createHandler: (strapi, context) => handler(strapi, context, (args) => listContentVariants(strapi, args))
2526
2584
  },
2585
+ {
2586
+ name: "experience_list_changes",
2587
+ title: "Experience: list the change log",
2588
+ description: "The change log, newest first: each create/update/delete of a variation, annotation, experiment or block with when, actor (mcp:token:<id>/user:<id>, system), source (mcp, api, system), reason, correlationId and the before/after records. Filter by page, section, variation, block, experiment, correlationId, actor, source or time; page with beforeId = nextBeforeId. Never contains visitor or profile data.",
2589
+ auth: read,
2590
+ telemetry: telemetry("list_changes"),
2591
+ resolveInputSchema: () => utils.z.object({
2592
+ targetUid: utils.z.string().optional().describe('Page content type, e.g. "api::home.home".'),
2593
+ targetDocumentId: utils.z.string().optional().describe("Page documentId (may be omitted for single types)."),
2594
+ locale: utils.z.string().nullable().optional(),
2595
+ sectionKey: utils.z.string().optional(),
2596
+ variantKey: utils.z.string().optional(),
2597
+ blockKey: utils.z.string().optional(),
2598
+ experimentKey: utils.z.string().optional(),
2599
+ entity: utils.z.enum(["annotation", "variation", "experiment", "block"]).optional(),
2600
+ action: utils.z.enum(["create", "update", "delete", "orphaned", "reactivated"]).optional(),
2601
+ actor: utils.z.string().optional().describe('e.g. "mcp:token:5/user:1".'),
2602
+ source: utils.z.enum(["mcp", "api", "system"]).optional(),
2603
+ correlationId: utils.z.string().optional().describe("Only the changes of this orchestration run."),
2604
+ since: utils.z.string().optional().describe("ISO 8601, inclusive."),
2605
+ until: utils.z.string().optional().describe("ISO 8601, inclusive."),
2606
+ beforeId: utils.z.number().int().optional().describe("Next page: the nextBeforeId of the previous call."),
2607
+ limit: utils.z.number().int().min(1).max(200).optional().describe("Default 50, max 200."),
2608
+ includeValues: utils.z.boolean().optional().describe("Include the before/after records (default true).")
2609
+ }),
2610
+ resolveOutputSchema: () => loose({ count: utils.z.number(), hasMore: utils.z.boolean(), changes: utils.z.array(loose()) }),
2611
+ createHandler: (strapi, context) => handler(strapi, context, (args) => listChanges(strapi, args))
2612
+ },
2527
2613
  {
2528
2614
  name: "experience_create_content_variant",
2529
2615
  title: "Experience: create a content variant (copy a block into a section)",
@@ -1858,6 +1858,64 @@ async function listContentVariants(strapi, args) {
1858
1858
  }));
1859
1859
  return { count: rows.length, targets };
1860
1860
  }
1861
+ const CHANGE_FILTERS = ["sectionKey", "variantKey", "blockKey", "experimentKey", "entity", "action", "actor", "source", "correlationId"];
1862
+ const MAX_CHANGES = 200;
1863
+ const isoOrThrow = (value, name) => {
1864
+ if (value === void 0) return void 0;
1865
+ if (Number.isNaN(Date.parse(value))) throw new ToolError(`${name} must be an ISO 8601 date-time, e.g. "2026-11-18T00:00:00Z".`);
1866
+ return new Date(value).toISOString();
1867
+ };
1868
+ async function listChanges(strapi, args) {
1869
+ const filters = {};
1870
+ if (args.targetUid) {
1871
+ const target = await resolveTarget(strapi, args.targetUid, args.targetDocumentId);
1872
+ filters.targetUid = target.uid;
1873
+ filters.targetDocumentId = target.documentId;
1874
+ } else if (args.targetDocumentId) {
1875
+ throw new ToolError("targetDocumentId needs targetUid.");
1876
+ }
1877
+ if (args.locale !== void 0) filters.targetLocale = args.locale === null ? { $null: true } : args.locale;
1878
+ for (const key of CHANGE_FILTERS) {
1879
+ if (args[key] !== void 0 && args[key] !== "") filters[key] = args[key];
1880
+ }
1881
+ const since = isoOrThrow(args.since, "since");
1882
+ const until = isoOrThrow(args.until, "until");
1883
+ if (since || until) filters.createdAt = { ...since ? { $gte: since } : {}, ...until ? { $lte: until } : {} };
1884
+ if (args.beforeId !== void 0) filters.id = { $lt: args.beforeId };
1885
+ const limit = Math.min(Math.max(Math.trunc(args.limit ?? 50), 1), MAX_CHANGES);
1886
+ const rows = await strapi.documents(CHANGE_UID).findMany({
1887
+ filters,
1888
+ sort: [{ createdAt: "desc" }, { id: "desc" }],
1889
+ pagination: { limit: limit + 1 }
1890
+ });
1891
+ const page = rows.slice(0, limit);
1892
+ const values = args.includeValues !== false;
1893
+ return {
1894
+ count: page.length,
1895
+ hasMore: rows.length > limit,
1896
+ nextBeforeId: rows.length > limit ? page[page.length - 1].id : null,
1897
+ changes: page.map((r) => ({
1898
+ id: r.id,
1899
+ at: r.createdAt,
1900
+ action: r.action,
1901
+ entity: r.entity,
1902
+ entityDocumentId: r.entityDocumentId ?? null,
1903
+ targetUid: r.targetUid ?? null,
1904
+ targetDocumentId: r.targetDocumentId ?? null,
1905
+ locale: r.targetLocale ?? null,
1906
+ sectionKey: r.sectionKey ?? null,
1907
+ variantKey: r.variantKey ?? null,
1908
+ blockKey: r.blockKey ?? null,
1909
+ componentUid: r.componentUid ?? null,
1910
+ experimentKey: r.experimentKey ?? null,
1911
+ actor: r.actor ?? null,
1912
+ source: r.source,
1913
+ reason: r.reason ?? null,
1914
+ correlationId: r.correlationId ?? null,
1915
+ ...values ? { before: r.before ?? null, after: r.after ?? null } : {}
1916
+ }))
1917
+ };
1918
+ }
1861
1919
  async function validateMapping(strapi, args) {
1862
1920
  const s = store$1(strapi);
1863
1921
  const vctx = await validationContext(strapi);
@@ -2508,7 +2566,7 @@ const EXPERIENCE_TOOLS = [
2508
2566
  {
2509
2567
  name: "experience_list_content_variants",
2510
2568
  title: "Experience: list sections and variations",
2511
- description: "Sections and their variations for one page, or across pages filtered by audience id, experiment key or section key. Inactive and orphaned mappings are left out unless includeInactive is true.",
2569
+ description: "Sections and their variations (which zone.* block a page shows per audience or experiment outcome) for one page, or across pages filtered by audience id, experiment key or section key. Inactive and orphaned mappings are left out unless includeInactive is true. Per-entry content variants (one entry, other copy per segment) belong to the content-variants plugin: variants_list_entry_variants.",
2512
2570
  auth: read,
2513
2571
  telemetry: telemetry("list_content_variants"),
2514
2572
  resolveInputSchema: () => z.object({
@@ -2523,6 +2581,34 @@ const EXPERIENCE_TOOLS = [
2523
2581
  resolveOutputSchema: () => loose({ count: z.number(), targets: z.array(loose()) }),
2524
2582
  createHandler: (strapi, context) => handler(strapi, context, (args) => listContentVariants(strapi, args))
2525
2583
  },
2584
+ {
2585
+ name: "experience_list_changes",
2586
+ title: "Experience: list the change log",
2587
+ description: "The change log, newest first: each create/update/delete of a variation, annotation, experiment or block with when, actor (mcp:token:<id>/user:<id>, system), source (mcp, api, system), reason, correlationId and the before/after records. Filter by page, section, variation, block, experiment, correlationId, actor, source or time; page with beforeId = nextBeforeId. Never contains visitor or profile data.",
2588
+ auth: read,
2589
+ telemetry: telemetry("list_changes"),
2590
+ resolveInputSchema: () => z.object({
2591
+ targetUid: z.string().optional().describe('Page content type, e.g. "api::home.home".'),
2592
+ targetDocumentId: z.string().optional().describe("Page documentId (may be omitted for single types)."),
2593
+ locale: z.string().nullable().optional(),
2594
+ sectionKey: z.string().optional(),
2595
+ variantKey: z.string().optional(),
2596
+ blockKey: z.string().optional(),
2597
+ experimentKey: z.string().optional(),
2598
+ entity: z.enum(["annotation", "variation", "experiment", "block"]).optional(),
2599
+ action: z.enum(["create", "update", "delete", "orphaned", "reactivated"]).optional(),
2600
+ actor: z.string().optional().describe('e.g. "mcp:token:5/user:1".'),
2601
+ source: z.enum(["mcp", "api", "system"]).optional(),
2602
+ correlationId: z.string().optional().describe("Only the changes of this orchestration run."),
2603
+ since: z.string().optional().describe("ISO 8601, inclusive."),
2604
+ until: z.string().optional().describe("ISO 8601, inclusive."),
2605
+ beforeId: z.number().int().optional().describe("Next page: the nextBeforeId of the previous call."),
2606
+ limit: z.number().int().min(1).max(200).optional().describe("Default 50, max 200."),
2607
+ includeValues: z.boolean().optional().describe("Include the before/after records (default true).")
2608
+ }),
2609
+ resolveOutputSchema: () => loose({ count: z.number(), hasMore: z.boolean(), changes: z.array(loose()) }),
2610
+ createHandler: (strapi, context) => handler(strapi, context, (args) => listChanges(strapi, args))
2611
+ },
2526
2612
  {
2527
2613
  name: "experience_create_content_variant",
2528
2614
  title: "Experience: create a content variant (copy a block into a section)",
@@ -222,6 +222,56 @@ export declare function listContentVariants(strapi: Core.Strapi, args: {
222
222
  }[];
223
223
  }[];
224
224
  }>;
225
+ export interface ListChangesArgs {
226
+ targetUid?: string;
227
+ targetDocumentId?: string;
228
+ locale?: string | null;
229
+ sectionKey?: string;
230
+ variantKey?: string;
231
+ blockKey?: string;
232
+ experimentKey?: string;
233
+ entity?: 'annotation' | 'variation' | 'experiment' | 'block';
234
+ action?: 'create' | 'update' | 'delete' | 'orphaned' | 'reactivated';
235
+ actor?: string;
236
+ source?: 'mcp' | 'api' | 'system';
237
+ correlationId?: string;
238
+ since?: string;
239
+ until?: string;
240
+ beforeId?: number;
241
+ limit?: number;
242
+ includeValues?: boolean;
243
+ }
244
+ /**
245
+ * The change log (plan §5.4), newest first: who changed which mapping or
246
+ * block, when, how (source) and in which run (correlationId), with the
247
+ * before/after records. Page with `beforeId` (the last id of a page).
248
+ */
249
+ export declare function listChanges(strapi: Core.Strapi, args: ListChangesArgs): Promise<{
250
+ count: number;
251
+ hasMore: boolean;
252
+ nextBeforeId: any;
253
+ changes: {
254
+ before?: any;
255
+ after?: any;
256
+ id: any;
257
+ at: any;
258
+ action: any;
259
+ entity: any;
260
+ entityDocumentId: any;
261
+ targetUid: any;
262
+ targetDocumentId: any;
263
+ locale: any;
264
+ sectionKey: any;
265
+ variantKey: any;
266
+ blockKey: any;
267
+ componentUid: any;
268
+ experimentKey: any;
269
+ actor: any;
270
+ source: any;
271
+ reason: any;
272
+ correlationId: any;
273
+ }[];
274
+ }>;
225
275
  export declare function validateMapping(strapi: Core.Strapi, args: {
226
276
  targetUid?: string;
227
277
  targetDocumentId?: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zachariaz/strapi-plugin-experience-context",
3
- "version": "0.1.0-dev.0",
3
+ "version": "0.1.0-dev.2",
4
4
  "description": "Strapi v5 plugin: read-only Experience Manager extension for inspecting and simulating context-aware content (concepts, audience variations, experiment outcomes) authored through MCP",
5
5
  "license": "MIT",
6
6
  "repository": {