@zachariaz/strapi-plugin-experience-context 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +86 -2
- package/dist/_chunks/en-8ms9Hfxr.mjs +27 -0
- package/dist/_chunks/en-yERKDiB0.js +27 -0
- package/dist/admin/index.js +464 -0
- package/dist/admin/index.mjs +448 -0
- package/dist/admin/src/api/client.d.ts +13 -0
- package/dist/admin/src/api/types.d.ts +93 -0
- package/dist/admin/src/api/useInspect.d.ts +3 -0
- package/dist/admin/src/components/BlockMarkers.d.ts +12 -0
- package/dist/admin/src/components/ExperienceModal.d.ts +28 -0
- package/dist/admin/src/components/HeaderBadge.d.ts +19 -0
- package/dist/admin/src/components/Initializer.d.ts +5 -0
- package/dist/admin/src/components/ModalTrigger.d.ts +10 -0
- package/dist/admin/src/contentManagerHooks/editView.d.ts +7 -0
- package/dist/admin/src/index.d.ts +17 -0
- package/dist/admin/src/pluginId.d.ts +2 -0
- package/dist/admin/src/utils/dzSlots.d.ts +16 -0
- package/dist/admin/src/utils/labels.d.ts +30 -0
- package/dist/admin/src/utils/markers.d.ts +12 -0
- package/dist/admin/src/utils/modal.d.ts +10 -0
- package/dist/admin/src/utils/targets.d.ts +12 -0
- package/dist/server/index.js +3780 -0
- package/dist/server/index.mjs +3781 -0
- package/dist/server/src/admin-api/access.d.ts +40 -0
- package/dist/server/src/admin-api/inspect.d.ts +132 -0
- package/dist/server/src/admin-api/mark.d.ts +9 -0
- package/dist/server/src/block-keys/index.d.ts +16 -0
- package/dist/server/src/block-keys/middleware.d.ts +17 -0
- package/dist/server/src/block-keys/stamp.d.ts +55 -0
- package/dist/server/src/block-keys/store.d.ts +33 -0
- package/dist/server/src/block-keys/targets.d.ts +43 -0
- package/dist/server/src/bootstrap.d.ts +16 -0
- package/dist/server/src/changes.d.ts +80 -0
- package/dist/server/src/config/index.d.ts +67 -0
- package/dist/server/src/constants.d.ts +18 -0
- package/dist/server/src/content-types/index.d.ts +309 -0
- package/dist/server/src/controllers/admin.d.ts +10 -0
- package/dist/server/src/controllers/experience.d.ts +15 -0
- package/dist/server/src/controllers/index.d.ts +16 -0
- package/dist/server/src/destroy.d.ts +5 -0
- package/dist/server/src/index.d.ts +441 -0
- package/dist/server/src/integrity/index.d.ts +34 -0
- package/dist/server/src/integrity/orphans.d.ts +40 -0
- package/dist/server/src/mcp/index.d.ts +2 -0
- package/dist/server/src/mcp/operations.d.ts +815 -0
- package/dist/server/src/mcp/permissions.d.ts +56 -0
- package/dist/server/src/mcp/tools.d.ts +59 -0
- package/dist/server/src/model/content.d.ts +32 -0
- package/dist/server/src/model/mapping.d.ts +90 -0
- package/dist/server/src/model/records.d.ts +132 -0
- package/dist/server/src/model/store.d.ts +44 -0
- package/dist/server/src/model/target.d.ts +40 -0
- package/dist/server/src/policies/index.d.ts +4 -0
- package/dist/server/src/rbac/index.d.ts +24 -0
- package/dist/server/src/read-path/editor.d.ts +28 -0
- package/dist/server/src/read-path/gate.d.ts +26 -0
- package/dist/server/src/read-path/index.d.ts +12 -0
- package/dist/server/src/read-path/loader.d.ts +31 -0
- package/dist/server/src/read-path/middleware.d.ts +32 -0
- package/dist/server/src/read-path/payload.d.ts +34 -0
- package/dist/server/src/read-path/populate.d.ts +6 -0
- package/dist/server/src/register.d.ts +14 -0
- package/dist/server/src/registry/index.d.ts +29 -0
- package/dist/server/src/registry/unomi.d.ts +53 -0
- package/dist/server/src/routes/index.d.ts +25 -0
- package/dist/server/src/services/index.d.ts +79 -0
- package/package.json +140 -4
- package/scripts/experience-smoke.mjs +430 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
/**
|
|
3
|
+
* Access rules of the read-only admin API: every admin who can read a
|
|
4
|
+
* content type in the Content Manager (and, for conditional or
|
|
5
|
+
* locale-limited roles, that document) may inspect its experience mappings.
|
|
6
|
+
* The routes additionally require the plugin's `read` admin action.
|
|
7
|
+
*/
|
|
8
|
+
/** The Content Manager permission inspection is gated on. */
|
|
9
|
+
export declare const CM_READ_ACTION = "plugin::content-manager.explorer.read";
|
|
10
|
+
export declare class AdminApiError extends Error {
|
|
11
|
+
readonly status: 400 | 403 | 404;
|
|
12
|
+
constructor(status: 400 | 403 | 404, message: string);
|
|
13
|
+
}
|
|
14
|
+
/** Validates `uid` against the configured targets. */
|
|
15
|
+
export declare const checkUid: (strapi: Core.Strapi, uid: unknown) => {
|
|
16
|
+
uid: string;
|
|
17
|
+
target: boolean;
|
|
18
|
+
};
|
|
19
|
+
export declare const checkLocale: (locale: unknown) => string | null;
|
|
20
|
+
/** Type-level Content Manager read check; documents are checked with {@link documentReadGuard}. */
|
|
21
|
+
export declare const canRead: (ability: any, uid: string) => boolean;
|
|
22
|
+
export interface DocumentReadGuard {
|
|
23
|
+
/** False when every read rule is unconditional: no document needs loading. */
|
|
24
|
+
readonly needsDocument: boolean;
|
|
25
|
+
canReadDocument(version: any): boolean;
|
|
26
|
+
}
|
|
27
|
+
/** For callers that already checked the documents (tests, server-side use). */
|
|
28
|
+
export declare const OPEN_GUARD: DocumentReadGuard;
|
|
29
|
+
/** Relations a permission condition may test (`admin::is-creator` uses `createdBy.id`). */
|
|
30
|
+
export declare const CONDITION_POPULATE: string[];
|
|
31
|
+
/**
|
|
32
|
+
* The Content Manager's permission checker for `uid`, so a role limited by
|
|
33
|
+
* conditions or locales sees only what the Content Manager would show it.
|
|
34
|
+
* Without the checker every document is denied.
|
|
35
|
+
*/
|
|
36
|
+
export declare const documentReadGuard: (strapi: Core.Strapi, ability: any, uid: string) => DocumentReadGuard;
|
|
37
|
+
/** The draft version (with the condition relations) a guard checks, or null. */
|
|
38
|
+
export declare const permissionVersion: (strapi: Core.Strapi, uid: string, documentId: string, locale: string | null) => Promise<import("@strapi/types/dist/modules/documents").AnyDocument | null>;
|
|
39
|
+
/** The locale to show when the request names none: i18n's default for localized types. */
|
|
40
|
+
export declare const resolveLocale: (strapi: Core.Strapi, uid: string, locale: string | null) => Promise<string | null>;
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
import { type ChecklistItem, type Snapshot } from '../model/mapping';
|
|
3
|
+
import { type AnnotationRecord, type VariationRecord } from '../model/records';
|
|
4
|
+
import { type BlockView } from '../model/target';
|
|
5
|
+
import { type DocumentReadGuard } from './access';
|
|
6
|
+
/**
|
|
7
|
+
* Read-only inspection for the Content Manager modal (plan §7.1): per block
|
|
8
|
+
* ABOUT (concepts), INTENDED FOR (audiences, traits, affinities), EXPERIMENT
|
|
9
|
+
* (key and outcome), FALLBACK (the section's default), CREATED VIA (agent /
|
|
10
|
+
* Strapi MCP, date, correlation id) and VALIDATION (the same checklist as
|
|
11
|
+
* `experience_validate_mapping`). Nothing here writes.
|
|
12
|
+
*/
|
|
13
|
+
export declare const HISTORY_LIMIT = 10;
|
|
14
|
+
export interface CreatedVia {
|
|
15
|
+
label: string;
|
|
16
|
+
source: string | null;
|
|
17
|
+
actor: string | null;
|
|
18
|
+
date: string | null;
|
|
19
|
+
correlationId: string | null;
|
|
20
|
+
}
|
|
21
|
+
export interface BlockCard {
|
|
22
|
+
blockKey: string;
|
|
23
|
+
index: number | null;
|
|
24
|
+
componentUid: string | null;
|
|
25
|
+
title: string | null;
|
|
26
|
+
/** `Hero · Variation "gold-electrician-hero"`. */
|
|
27
|
+
heading: string;
|
|
28
|
+
role: 'default' | 'variation' | 'outcome' | 'concepts';
|
|
29
|
+
sectionKey: string | null;
|
|
30
|
+
variantKey: string | null;
|
|
31
|
+
status: 'active' | 'inactive' | 'orphaned' | null;
|
|
32
|
+
about: string[];
|
|
33
|
+
intendedFor: string[];
|
|
34
|
+
/** `split`: the traffic split, e.g. `a 90% · b 10%` (equal split without weights). */
|
|
35
|
+
experiment: {
|
|
36
|
+
key: string;
|
|
37
|
+
outcome: string;
|
|
38
|
+
name: string | null;
|
|
39
|
+
status: string | null;
|
|
40
|
+
split: string | null;
|
|
41
|
+
} | null;
|
|
42
|
+
fallback: {
|
|
43
|
+
blockKey: string;
|
|
44
|
+
label: string;
|
|
45
|
+
} | null;
|
|
46
|
+
createdVia: CreatedVia | null;
|
|
47
|
+
validation: string[];
|
|
48
|
+
}
|
|
49
|
+
export declare const createdVia: (row: Pick<VariationRecord, 'source' | 'createdBy' | 'createdAt' | 'correlationId'> | Pick<AnnotationRecord, 'source' | 'createdBy' | 'createdAt' | 'correlationId'> | undefined) => CreatedVia | null;
|
|
50
|
+
/** Checklist lines that concern one block: its section, its variation, its annotation and its experiment. */
|
|
51
|
+
export declare const itemsForBlock: (items: ChecklistItem[], v: VariationRecord | undefined, blockKey: string) => string[];
|
|
52
|
+
/** The modal card of one block (pure; exported for tests). */
|
|
53
|
+
export declare function blockCard(snap: Snapshot, items: ChecklistItem[], blockKey: string, block: BlockView | undefined): BlockCard;
|
|
54
|
+
/** `GET /inspect/:uid/:documentId?locale=`: everything the read-only modal, badge and markers show. */
|
|
55
|
+
export declare function inspect(strapi: Core.Strapi, query: {
|
|
56
|
+
uid?: unknown;
|
|
57
|
+
documentId?: unknown;
|
|
58
|
+
locale?: unknown;
|
|
59
|
+
}, guard?: DocumentReadGuard): Promise<{
|
|
60
|
+
target: null;
|
|
61
|
+
locale?: undefined;
|
|
62
|
+
summary?: undefined;
|
|
63
|
+
page?: undefined;
|
|
64
|
+
blocks?: undefined;
|
|
65
|
+
byBlockKey?: undefined;
|
|
66
|
+
orphaned?: undefined;
|
|
67
|
+
experiments?: undefined;
|
|
68
|
+
validation?: undefined;
|
|
69
|
+
changes?: undefined;
|
|
70
|
+
} | {
|
|
71
|
+
target: {
|
|
72
|
+
uid: string;
|
|
73
|
+
documentId: string;
|
|
74
|
+
kind: "collectionType" | "singleType";
|
|
75
|
+
localized: boolean;
|
|
76
|
+
};
|
|
77
|
+
locale: string | null;
|
|
78
|
+
summary: {
|
|
79
|
+
sections: number;
|
|
80
|
+
variations: number;
|
|
81
|
+
concepts: number;
|
|
82
|
+
annotatedBlocks: number;
|
|
83
|
+
experiments: {
|
|
84
|
+
key: string;
|
|
85
|
+
name: string | null;
|
|
86
|
+
status: import("@zachariaz/experience-context-core").ExperimentStatus;
|
|
87
|
+
running: boolean;
|
|
88
|
+
}[];
|
|
89
|
+
inactive: number;
|
|
90
|
+
orphaned: number;
|
|
91
|
+
errors: number;
|
|
92
|
+
warnings: number;
|
|
93
|
+
};
|
|
94
|
+
page: {
|
|
95
|
+
concepts: string[];
|
|
96
|
+
};
|
|
97
|
+
blocks: {
|
|
98
|
+
index: number;
|
|
99
|
+
blockKey: string | null;
|
|
100
|
+
componentUid: string;
|
|
101
|
+
summary: string;
|
|
102
|
+
title: string | null;
|
|
103
|
+
}[];
|
|
104
|
+
byBlockKey: Record<string, BlockCard>;
|
|
105
|
+
orphaned: BlockCard[];
|
|
106
|
+
experiments: import("@zachariaz/experience-context-core").Experiment[];
|
|
107
|
+
validation: {
|
|
108
|
+
ok: boolean;
|
|
109
|
+
errors: import("@zachariaz/experience-context-core").ValidationIssue[];
|
|
110
|
+
warnings: import("@zachariaz/experience-context-core").ValidationIssue[];
|
|
111
|
+
checklist: string[];
|
|
112
|
+
};
|
|
113
|
+
changes: {
|
|
114
|
+
createdAt: any;
|
|
115
|
+
action: any;
|
|
116
|
+
entity: any;
|
|
117
|
+
actor: any;
|
|
118
|
+
source: any;
|
|
119
|
+
sectionKey: any;
|
|
120
|
+
variantKey: any;
|
|
121
|
+
blockKey: any;
|
|
122
|
+
experimentKey: any;
|
|
123
|
+
correlationId: any;
|
|
124
|
+
}[];
|
|
125
|
+
}>;
|
|
126
|
+
/** `POST /explain`: the shared explanation for one document and a synthetic context. Reads only. */
|
|
127
|
+
export declare function explain(strapi: Core.Strapi, body: {
|
|
128
|
+
uid?: unknown;
|
|
129
|
+
documentId?: unknown;
|
|
130
|
+
locale?: unknown;
|
|
131
|
+
context?: unknown;
|
|
132
|
+
}, guard?: DocumentReadGuard): Promise<import("@zachariaz/experience-context-core").ResolutionExplanation>;
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
/**
|
|
3
|
+
* Register phase: marks every configured target type with
|
|
4
|
+
* `pluginOptions['experience-context'] = { target: true }`. The
|
|
5
|
+
* Content Manager passes `pluginOptions` into the list and edit layouts'
|
|
6
|
+
* `options`, so the admin hooks know which types to decorate without an
|
|
7
|
+
* extra request (the content-variants pattern).
|
|
8
|
+
*/
|
|
9
|
+
export declare function markTargetTypes(strapi: Core.Strapi): string[];
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
import { type BlockKeyTargets } from './targets';
|
|
3
|
+
export { BLOCK_KEY, BLOCK_KEY_ATTRIBUTE, TARGET_COMPONENT_PREFIX, TARGET_DYNAMIC_ZONES } from './targets';
|
|
4
|
+
export type { BlockKeyTargets } from './targets';
|
|
5
|
+
export type { BackfillOptions, BackfillReport } from './store';
|
|
6
|
+
export declare const blockKeyTargets: (strapi: Core.Strapi) => BlockKeyTargets;
|
|
7
|
+
/** Register phase: add the hidden attribute before the schema sync. */
|
|
8
|
+
export declare function registerBlockKeys(strapi: Core.Strapi): void;
|
|
9
|
+
/** Store key of the one-time bootstrap backfill; it reruns when the targets change. */
|
|
10
|
+
export declare const BACKFILL_STORE_KEY = "block-key-backfill";
|
|
11
|
+
export declare const targetsSignature: (targets: BlockKeyTargets) => string;
|
|
12
|
+
/**
|
|
13
|
+
* Bootstrap phase: stamp writes from now on, then key existing content once
|
|
14
|
+
* per target set (stored in the core store, so restarts don't rescan).
|
|
15
|
+
*/
|
|
16
|
+
export declare function bootstrapBlockKeys(strapi: Core.Strapi): Promise<void>;
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
import type { BlockKeyTargets } from './targets';
|
|
3
|
+
/** Locales a publish call covers; `undefined` means "don't filter". */
|
|
4
|
+
export declare function publishLocales(locale: unknown): string[] | undefined;
|
|
5
|
+
/**
|
|
6
|
+
* Document Service middleware that keeps `blockKey` on every targeted block:
|
|
7
|
+
*
|
|
8
|
+
* - `create` / `update` / `clone`: stamps the targeted dynamic zones present
|
|
9
|
+
* in `params.data` (missing keys, duplicate ids and keys, stored-key reuse).
|
|
10
|
+
* A write without the dynamic zone leaves the stored blocks alone.
|
|
11
|
+
* - `publish`: before the draft is copied, keys any draft block that has none
|
|
12
|
+
* yet (rows written before the plugin, or by raw database writes), so the
|
|
13
|
+
* published version gets the same keys.
|
|
14
|
+
*
|
|
15
|
+
* Every other action passes through.
|
|
16
|
+
*/
|
|
17
|
+
export declare function registerBlockKeyMiddleware(strapi: Core.Strapi, targets: BlockKeyTargets): void;
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { BLOCK_KEY } from './targets';
|
|
2
|
+
/**
|
|
3
|
+
* Pure stamping rules for one dynamic-zone payload (PR-01 mitigations M1–M3).
|
|
4
|
+
*
|
|
5
|
+
* - M1: a key that is missing, `null`, not a string or blank (`''` from
|
|
6
|
+
* Experience Builder's default props) is absent and gets a new uuid.
|
|
7
|
+
* - M2 (K6): a later entry that repeats an earlier entry's component `id` loses
|
|
8
|
+
* its `id`, so Strapi creates a new row instead of writing both entries into
|
|
9
|
+
* one (Puck's duplicate copies `_strapiId` and `blockKey`). A later entry
|
|
10
|
+
* that repeats an earlier key gets a new key. The first occurrence keeps
|
|
11
|
+
* both its id and its key, so the original block keeps its mappings and the
|
|
12
|
+
* copy starts with none.
|
|
13
|
+
* - M3: an entry with an `id` but no key reuses that component row's stored
|
|
14
|
+
* key (history restore of a version saved before keys existed, clients
|
|
15
|
+
* that drop the field). A stored key already used earlier in the payload
|
|
16
|
+
* is not reused.
|
|
17
|
+
*
|
|
18
|
+
* Existing, unique keys are never changed.
|
|
19
|
+
*/
|
|
20
|
+
export type StampKind = 'kept' | 'reused' | 'stamped' | 'regenerated';
|
|
21
|
+
export interface StampEvent {
|
|
22
|
+
index: number;
|
|
23
|
+
component: string;
|
|
24
|
+
kind: StampKind;
|
|
25
|
+
key: string;
|
|
26
|
+
/** the entry repeated an earlier entry's component id, which was removed */
|
|
27
|
+
droppedId?: boolean;
|
|
28
|
+
}
|
|
29
|
+
export interface Block {
|
|
30
|
+
__component?: unknown;
|
|
31
|
+
id?: unknown;
|
|
32
|
+
[BLOCK_KEY]?: unknown;
|
|
33
|
+
[field: string]: unknown;
|
|
34
|
+
}
|
|
35
|
+
export interface StampOptions {
|
|
36
|
+
isKeyed: (component: string) => boolean;
|
|
37
|
+
/** stored key of component row `id`, if known (M3) */
|
|
38
|
+
storedKey?: (component: string, id: string) => string | undefined;
|
|
39
|
+
newKey?: () => string;
|
|
40
|
+
}
|
|
41
|
+
export declare const hasKey: (value: unknown) => value is string;
|
|
42
|
+
/**
|
|
43
|
+
* Component rows whose stored key may be needed (M3): keyed entries with an
|
|
44
|
+
* `id` and no key. Grouped by component uid.
|
|
45
|
+
*/
|
|
46
|
+
export declare function lookupsFor(blocks: unknown, isKeyed: StampOptions['isKeyed']): Map<string, string[]>;
|
|
47
|
+
/** Stamps `blocks` in place. Returns one event per keyed entry. */
|
|
48
|
+
export declare function stampBlocks(blocks: unknown, options: StampOptions): StampEvent[];
|
|
49
|
+
/**
|
|
50
|
+
* Backfill pairing (draft ↔ published, by position). Returns the key each
|
|
51
|
+
* entry of `blocks` should have, or `undefined` where the stored key stays.
|
|
52
|
+
* `partner[i]` is the other version's entry at the same position: its key is
|
|
53
|
+
* reused when it is the same component and not taken yet.
|
|
54
|
+
*/
|
|
55
|
+
export declare function pairKeys(blocks: readonly Block[], partner: readonly Block[], isKeyed: StampOptions['isKeyed'], newKey?: () => string): Array<string | undefined>;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
import { type StampEvent } from './stamp';
|
|
3
|
+
import { type BlockKeyTargets } from './targets';
|
|
4
|
+
export interface BackfillTypeReport {
|
|
5
|
+
rows: number;
|
|
6
|
+
documents: number;
|
|
7
|
+
blocks: number;
|
|
8
|
+
updated: number;
|
|
9
|
+
}
|
|
10
|
+
export interface BackfillReport {
|
|
11
|
+
dryRun: boolean;
|
|
12
|
+
updated: number;
|
|
13
|
+
contentTypes: Record<string, BackfillTypeReport>;
|
|
14
|
+
}
|
|
15
|
+
export interface BackfillOptions {
|
|
16
|
+
dryRun?: boolean;
|
|
17
|
+
/** limit to these content types (default: every targeted one) */
|
|
18
|
+
contentTypes?: string[];
|
|
19
|
+
/** limit to one document (used on publish) */
|
|
20
|
+
documentId?: string;
|
|
21
|
+
/** limit to these locales (used on publish) */
|
|
22
|
+
locales?: string[];
|
|
23
|
+
/** documents per populated read (default 50) */
|
|
24
|
+
batchSize?: number;
|
|
25
|
+
}
|
|
26
|
+
/** Stamps every targeted zone present in a create/update/clone `data` in place. */
|
|
27
|
+
export declare function stampPayload(strapi: Core.Strapi, targets: BlockKeyTargets, uid: string, data: unknown): Promise<StampEvent[]>;
|
|
28
|
+
/**
|
|
29
|
+
* Keys every targeted block that lacks one (or repeats one within its row).
|
|
30
|
+
* Draft and published rows of the same document and locale are paired by
|
|
31
|
+
* position, so both versions of a block end up with the same key.
|
|
32
|
+
*/
|
|
33
|
+
export declare function backfill(strapi: Core.Strapi, targets: BlockKeyTargets, options?: BackfillOptions): Promise<BackfillReport>;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
/**
|
|
3
|
+
* Which dynamic zones and components carry a `blockKey` (epic Q2).
|
|
4
|
+
*
|
|
5
|
+
* Targets are the `zone.*` blocks in the `content` dynamic zone of every
|
|
6
|
+
* configured content type. The `configuration` dynamic zone (fixed-slot
|
|
7
|
+
* `commerce.*` / `marketing.*` blocks) is not targetable.
|
|
8
|
+
*/
|
|
9
|
+
export declare const BLOCK_KEY = "blockKey";
|
|
10
|
+
export declare const TARGET_DYNAMIC_ZONES: readonly string[];
|
|
11
|
+
export declare const TARGET_COMPONENT_PREFIX = "zone.";
|
|
12
|
+
/** The attribute the plugin adds to every keyed component (PR-01 decision). */
|
|
13
|
+
export declare const BLOCK_KEY_ATTRIBUTE: Readonly<{
|
|
14
|
+
type: "string";
|
|
15
|
+
visible: false;
|
|
16
|
+
configurable: false;
|
|
17
|
+
}>;
|
|
18
|
+
export interface BlockKeyTargets {
|
|
19
|
+
/** content type uid → its targeted dynamic zone attribute names */
|
|
20
|
+
zonesByUid: Map<string, string[]>;
|
|
21
|
+
/** component uids that carry a `blockKey` */
|
|
22
|
+
keyedComponents: Set<string>;
|
|
23
|
+
}
|
|
24
|
+
type Attributes = Record<string, {
|
|
25
|
+
type?: string;
|
|
26
|
+
components?: string[];
|
|
27
|
+
} | undefined>;
|
|
28
|
+
/** Pure: works on plain `{ uid: { attributes } }` maps so it is testable. */
|
|
29
|
+
export declare function resolveTargets(contentTypes: Record<string, {
|
|
30
|
+
attributes?: Attributes;
|
|
31
|
+
} | undefined>, configured: readonly string[]): BlockKeyTargets;
|
|
32
|
+
export declare function getTargets(strapi: Core.Strapi, configured: readonly string[]): BlockKeyTargets;
|
|
33
|
+
/**
|
|
34
|
+
* Register phase: add the hidden `blockKey` attribute to every keyed
|
|
35
|
+
* component. Runs before the database schema sync, so Strapi creates the
|
|
36
|
+
* `block_key` column itself. `visible:false` keeps it out of the Content
|
|
37
|
+
* Manager edit layout; the CM form still sends it back on save.
|
|
38
|
+
*
|
|
39
|
+
* Returns the components that got the attribute (already-present ones are
|
|
40
|
+
* left as they are).
|
|
41
|
+
*/
|
|
42
|
+
export declare function injectBlockKeyAttribute(strapi: Core.Strapi, targets: BlockKeyTargets): string[];
|
|
43
|
+
export {};
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
/**
|
|
3
|
+
* Bootstrap phase. Logs which configured content types exist (a typo in
|
|
4
|
+
* `contentTypes` is visible at startup instead of silently disabling the
|
|
5
|
+
* type), registers the admin actions that gate the MCP tools and the admin
|
|
6
|
+
* API (and, with `roles: true`, provisions the add-on roles), starts
|
|
7
|
+
* `blockKey` stamping and the one-time backfill, then the
|
|
8
|
+
* `?withExperience` read path (registered after content-variants'
|
|
9
|
+
* bootstrap, so its Document Service middleware runs inside
|
|
10
|
+
* content-variants'), and finally orphan detection, the delete cascade and
|
|
11
|
+
* the `experience.update` webhook event.
|
|
12
|
+
*/
|
|
13
|
+
declare const bootstrap: ({ strapi }: {
|
|
14
|
+
strapi: Core.Strapi;
|
|
15
|
+
}) => Promise<void>;
|
|
16
|
+
export default bootstrap;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
/**
|
|
3
|
+
* The change log (plan §5.4) and the `experience.update` webhook.
|
|
4
|
+
*
|
|
5
|
+
* Every change to an annotation, variation or experiment, and every content
|
|
6
|
+
* block an MCP tool adds or removes, goes through {@link recordChange}: it
|
|
7
|
+
* appends one row to the append-only `change` log. Webhook targets are
|
|
8
|
+
* collected in a {@link ChangeBatch}; `flush()` emits ONE `experience.update`
|
|
9
|
+
* event per write operation after the transaction commits, which Strapi
|
|
10
|
+
* delivers to every webhook subscribed to it (Settings → Webhooks).
|
|
11
|
+
*
|
|
12
|
+
* The log never stores visitor context or profile data: before/after are
|
|
13
|
+
* reduced to the whitelisted record fields of their entity ({@link auditRecord}).
|
|
14
|
+
*/
|
|
15
|
+
/** Strapi webhook event (Settings → Webhooks lists it under this name). */
|
|
16
|
+
export declare const WEBHOOK_EVENT = "experience.update";
|
|
17
|
+
export declare const WEBHOOK_EVENT_KEY = "EXPERIENCE_UPDATE";
|
|
18
|
+
export type ChangeAction = 'create' | 'update' | 'delete' | 'orphaned' | 'reactivated';
|
|
19
|
+
export type ChangeEntity = 'annotation' | 'variation' | 'experiment' | 'block';
|
|
20
|
+
export type ChangeSource = 'mcp' | 'api' | 'system';
|
|
21
|
+
/** Actor of changes the plugin makes itself (orphan recompute, delete cascade). */
|
|
22
|
+
export declare const SYSTEM_ACTOR = "system";
|
|
23
|
+
/** The fields of each entity that may appear in before/after. Nothing else is logged. */
|
|
24
|
+
export declare const AUDIT_FIELDS: Record<ChangeEntity, readonly string[]>;
|
|
25
|
+
/** Reduces a record to its entity's audit fields (no visitor or profile data can slip in). */
|
|
26
|
+
export declare function auditRecord(entity: ChangeEntity, record: Record<string, unknown> | null | undefined): Record<string, unknown> | null;
|
|
27
|
+
export interface WebhookTarget {
|
|
28
|
+
uid: string;
|
|
29
|
+
documentId: string;
|
|
30
|
+
locale: string | null;
|
|
31
|
+
}
|
|
32
|
+
export interface ChangeEntry {
|
|
33
|
+
action: ChangeAction;
|
|
34
|
+
entity: ChangeEntity;
|
|
35
|
+
entityDocumentId?: string | null;
|
|
36
|
+
before: Record<string, any> | null;
|
|
37
|
+
after: Record<string, any> | null;
|
|
38
|
+
actor?: string | null;
|
|
39
|
+
source: ChangeSource;
|
|
40
|
+
/** Why the system made the change, e.g. `content-update`, `document-deleted`, or the agent's reason. */
|
|
41
|
+
reason?: string | null;
|
|
42
|
+
correlationId?: string | null;
|
|
43
|
+
}
|
|
44
|
+
/** Collects the targets and experiment keys of one write operation for a single webhook event. */
|
|
45
|
+
export declare class ChangeBatch {
|
|
46
|
+
readonly targets: Map<string, WebhookTarget>;
|
|
47
|
+
readonly experiments: Set<string>;
|
|
48
|
+
count: number;
|
|
49
|
+
addTarget(uid: string | null | undefined, documentId: string | null | undefined, locale: string | null | undefined): void;
|
|
50
|
+
addExperiment(key: string | null | undefined): void;
|
|
51
|
+
get empty(): boolean;
|
|
52
|
+
payload(): {
|
|
53
|
+
targets: WebhookTarget[];
|
|
54
|
+
experiments: string[];
|
|
55
|
+
};
|
|
56
|
+
/** Emits one `experience.update` after commit (nothing when the batch is empty). */
|
|
57
|
+
flush(strapi: Core.Strapi): Promise<void>;
|
|
58
|
+
}
|
|
59
|
+
/** Experiment key a change is about: the experiment itself, or the one a variation maps to. */
|
|
60
|
+
export declare const experimentKeyOf: (entry: Pick<ChangeEntry, 'entity' | 'before' | 'after'>) => string | null;
|
|
61
|
+
/**
|
|
62
|
+
* Emits the webhook event once the surrounding database transaction has
|
|
63
|
+
* committed, or right away outside a transaction. A rolled-back write emits
|
|
64
|
+
* nothing, so subscribers never revalidate for a change that did not happen.
|
|
65
|
+
*/
|
|
66
|
+
export declare function emitAfterCommit(strapi: Core.Strapi, payload: ReturnType<ChangeBatch['payload']>): Promise<void>;
|
|
67
|
+
/**
|
|
68
|
+
* Appends one row to the change log and adds its target and experiment to
|
|
69
|
+
* `batch`. Without a batch, the event is emitted right away (after commit).
|
|
70
|
+
*/
|
|
71
|
+
export declare function recordChange(strapi: Core.Strapi, entry: ChangeEntry, batch?: ChangeBatch): Promise<void>;
|
|
72
|
+
/** Bootstrap: makes the event selectable in Settings → Webhooks. */
|
|
73
|
+
export declare function registerWebhookEvent(strapi: Core.Strapi): void;
|
|
74
|
+
/** Audit entries, newest first. */
|
|
75
|
+
export declare function changeHistory(strapi: Core.Strapi, filters: {
|
|
76
|
+
targetUid?: string;
|
|
77
|
+
targetDocumentId?: string;
|
|
78
|
+
experimentKey?: string;
|
|
79
|
+
entityDocumentId?: string;
|
|
80
|
+
}, limit?: number): Promise<any[]>;
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
import type { Core } from '@strapi/strapi';
|
|
2
|
+
import { type Preset, type RegistryEntry } from '@zachariaz/experience-context-core';
|
|
3
|
+
import type { UnomiSourceConfig } from '../registry/unomi';
|
|
4
|
+
/**
|
|
5
|
+
* Plugin config (`config/plugins.ts` → `'experience-context': { config: { ... } }`).
|
|
6
|
+
*
|
|
7
|
+
* `contentTypes`: the content types whose document (page) and `zone.*` blocks
|
|
8
|
+
* in their `content` dynamic zone can carry experience mappings. Blocks in a
|
|
9
|
+
* `configuration` dynamic zone are not targetable. Unset means
|
|
10
|
+
* `DEFAULT_CONTENT_TYPES`; a value replaces the list as a whole.
|
|
11
|
+
*
|
|
12
|
+
* `registry`: the static v1 registry (plan §5.3), normally the app's
|
|
13
|
+
* `config/experience-registry.ts`: known audience, trait, affinity and
|
|
14
|
+
* concept ids with labels. content-variants segments that have an
|
|
15
|
+
* `externalId` are added as `audience/<slug>` at runtime; experiments come
|
|
16
|
+
* from the plugin's own collection. An id that is not in the registry is a
|
|
17
|
+
* warning, never an error.
|
|
18
|
+
*
|
|
19
|
+
* `presets`: named synthetic contexts for the Experience Builder simulator
|
|
20
|
+
* (plan §7.4), normally `config/experience-presets.ts`. Rejected at startup
|
|
21
|
+
* when one contains a real-looking identifier (P1).
|
|
22
|
+
*
|
|
23
|
+
* `unomi`: reads the audience and affinity definitions live from Unomi
|
|
24
|
+
* (`{ url, username?, password?, scope?, ttlSeconds?, timeoutMs? }`, see
|
|
25
|
+
* ../registry/unomi) and adds them to the registry. Unset or an empty `url`
|
|
26
|
+
* = off. Definitions only; a failing Unomi never fails a request.
|
|
27
|
+
*
|
|
28
|
+
* `roles`: true provisions the add-on admin roles (see ../rbac) at startup:
|
|
29
|
+
* created when missing, missing plugin actions added; nothing else on any
|
|
30
|
+
* role is changed or removed. Default false.
|
|
31
|
+
*
|
|
32
|
+
* No option has an array default in `default`: Strapi merges plugin config
|
|
33
|
+
* with `_.defaultsDeep({}, user, default)`, which merges arrays by index.
|
|
34
|
+
*/
|
|
35
|
+
export interface RegistryConfig {
|
|
36
|
+
audiences?: RegistryEntry[];
|
|
37
|
+
traits?: RegistryEntry[];
|
|
38
|
+
affinities?: RegistryEntry[];
|
|
39
|
+
concepts?: RegistryEntry[];
|
|
40
|
+
}
|
|
41
|
+
export interface PluginConfig {
|
|
42
|
+
contentTypes?: string[];
|
|
43
|
+
registry?: RegistryConfig;
|
|
44
|
+
presets?: Preset[];
|
|
45
|
+
roles?: boolean;
|
|
46
|
+
unomi?: UnomiSourceConfig;
|
|
47
|
+
}
|
|
48
|
+
export declare const DEFAULT_CONTENT_TYPES: string[];
|
|
49
|
+
/** `contentTypes` with the default applied (unset → `DEFAULT_CONTENT_TYPES`). */
|
|
50
|
+
export declare function resolveContentTypes(value: unknown): string[];
|
|
51
|
+
/** The effective `contentTypes` of a running app (a copy; safe to mutate). */
|
|
52
|
+
export declare const configuredContentTypes: (strapi: Core.Strapi) => string[];
|
|
53
|
+
export declare const configuredRegistry: (strapi: Core.Strapi) => RegistryConfig;
|
|
54
|
+
export declare const configuredUnomi: (strapi: Core.Strapi) => UnomiSourceConfig | undefined;
|
|
55
|
+
export declare const configuredRoles: (strapi: Core.Strapi) => boolean;
|
|
56
|
+
export declare const configuredPresets: (strapi: Core.Strapi) => Preset[];
|
|
57
|
+
/** Problems in the registry config, one line each (empty = valid). */
|
|
58
|
+
export declare function registryProblems(registry: unknown): string[];
|
|
59
|
+
/** Problems in the `unomi` option, one line each. */
|
|
60
|
+
export declare function unomiProblems(unomi: unknown): string[];
|
|
61
|
+
/** Problems in the presets config (P1 and shape), one line each. */
|
|
62
|
+
export declare function presetProblems(presets: unknown): string[];
|
|
63
|
+
declare const _default: {
|
|
64
|
+
default: PluginConfig;
|
|
65
|
+
validator(config: PluginConfig): void;
|
|
66
|
+
};
|
|
67
|
+
export default _default;
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
export declare const PLUGIN_ID = "experience-context";
|
|
2
|
+
/** Prefix for every log line this plugin writes. */
|
|
3
|
+
export declare const LOG_PREFIX = "[experience-context]";
|
|
4
|
+
export declare const ANNOTATION_UID: "plugin::experience-context.annotation";
|
|
5
|
+
export declare const VARIATION_UID: "plugin::experience-context.variation";
|
|
6
|
+
export declare const EXPERIMENT_UID: "plugin::experience-context.experiment";
|
|
7
|
+
export declare const CHANGE_UID: "plugin::experience-context.change";
|
|
8
|
+
/** The dynamic zone whose `zone.*` blocks can be annotated and grouped into sections. */
|
|
9
|
+
export declare const CONTENT_ZONE = "content";
|
|
10
|
+
/** Key the read path adds to documents and blocks, and strips from writes. */
|
|
11
|
+
export declare const EXPERIENCE_KEY = "_experience";
|
|
12
|
+
/** Query parameter that turns the read path on. */
|
|
13
|
+
export declare const FLAG = "withExperience";
|
|
14
|
+
/**
|
|
15
|
+
* The agent instruction (plan §5.2). Part of every write tool description
|
|
16
|
+
* and of CLAUDE.md.
|
|
17
|
+
*/
|
|
18
|
+
export declare const AGENT_INSTRUCTION = "Strapi MCP creates and maps content alternatives. If the customer context you need (audience, trait, affinity, experiment) does not exist, find or create it with Unomi MCP first, then reference its id in Strapi. Never describe customer conditions in Strapi.";
|