@contentchef/contentchef-types 11.0.0-alpha.5 → 11.0.0-alpha.6

package/lib/api/Audience.ts

@@ -1,6 +1,6 @@
 import { AuthorResponse } from './Author';
 import { PagedListResponse } from './common';
-import { ContentDefinitionId } from './ContentDefinition';
+import { DimensionAssignment } from './Dimension';
 
 /**
  * The audience unique id
@@ -8,34 +8,82 @@ import { ContentDefinitionId } from './ContentDefinition';
 export type AudienceId = number;
 
 /**
- * An audience's mnemonicId and every one of its keys must match this pattern: lowercase, digits,
- * underscore and hyphen. Stricter than the other authoring mnemonicIds on purpose, because both halves
- * travel in the delivery `audiences` query param and are compared against strings a client supplies
+ * An audience's mnemonicId must match this pattern, and is at least 2 characters long. Lowercase like
+ * a dimension's, and immutable once created: contents, CSV files, the publishing snapshot and delivery
+ * all reference an audience by it
  */
 export const AUDIENCE_NAME_PATTERN = /^[a-z0-9_-]+$/;
 
 /**
- * This type represent one key of an audience, that is one of the values a visitor can have for it
+ * This type represent the condition of an audience rule on a single dimension: the visitor's value for
+ * [[dimension]] has to be one of [[in]]
  */
-export type AudienceKey = {
+export type DimensionPredicate = {
     /**
-     * The key, matching [[AUDIENCE_NAME_PATTERN]]
+     * The mnemonic id of the dimension this predicate constrains
      */
-    key: string;
+    dimension: string;
     /**
-     * A deprecated key cannot be referenced by new content rules, while every rule already written
-     * keeps resolving. The flag toggles both ways
+     * The keys of the dimension that satisfy this predicate, at least one
      */
-    deprecated?: boolean;
+    in: string[];
+    /**
+     * Set this value to also satisfy the predicate when the dimension was not provided at all
+     *
+     * Not-provided is not a key, so no list of keys can express it, and an enumeration would silently
+     * narrow the moment a key is added to the dimension. A key that was provided but is not listed does
+     * not satisfy this flag: the audience simply does not match
+     */
+    orUnset?: boolean;
+};
+
+/**
+ * This type represent a condition satisfied when every child condition is satisfied
+ */
+export type AllDimensionPredicate = {
+    all: AudienceRule[];
+};
+
+/**
+ * This type represent a condition satisfied when at least one child condition is satisfied
+ */
+export type AnyDimensionPredicate = {
+    any: AudienceRule[];
+};
+
+/**
+ * This type represent the rule of an audience: or within a dimension, and between dimensions
+ *
+ * The stored form is a tree so that new kinds of condition stay additive, but an editor only needs to
+ * build an [[AllDimensionPredicate]] of one [[DimensionPredicate]] per dimension. A dimension the rule
+ * does not mention is unconstrained, which is a different thing from one listed with
+ * [[DimensionPredicate.orUnset]]. `{ all: [] }` matches everyone
+ */
+export type AudienceRule = DimensionPredicate | AllDimensionPredicate | AnyDimensionPredicate;
+
+/**
+ * This type represent one dimension key an audience rule references. `key` is absent for a rule that
+ * constrains the dimension without naming a key
+ */
+export type DimensionKeyReference = {
+    /**
+     * The dimension mnemonic id
+     */
+    dimension: string;
+    /**
+     * The key, absent when the rule names none
+     */
+    key?: string;
 };
 
 /**
- * This type represent the model of an audience, that is a dimension a content can vary by - `gender`,
- * `loyalty`, `auth_status` - holding the fixed set of keys a visitor can have for it
+ * This type represent the model of an audience, that is a named rule over dimensions -
+ * "authenticated users with a silver card" - written once and referenced by mnemonicId from every
+ * content that wants it
  *
- * Contents reference an audience by mnemonicId and key inside their rules, and definitions by
- * mnemonicId, so audiences are archived and never deleted, and a key can only be removed or renamed
- * while no content references it
+ * Nothing to evaluate lives in a content: a personalized field lists audiences, and the rules stay
+ * here. Audiences are archived and never deleted, and archiving is refused while a content still
+ * references one
  */
 export type AudienceResponse = {
     /**
@@ -51,9 +99,14 @@ export type AudienceResponse = {
      */
     mnemonicId: string;
     /**
-     * The keys a visitor can hold for this audience, each carrying its own deprecation state
+     * The rule that decides whether a visitor belongs to this audience
+     */
+    rule: AudienceRule;
+    /**
+     * The dimension keys the rule references, derived from it on every save. This is what makes a
+     * dimension key removable or not
      */
-    keys: AudienceKey[];
+    usedDimensionKeys: DimensionKeyReference[];
     /**
      * The archived status of the audience
      */
@@ -109,48 +162,25 @@ export type ListAudiencesRequest = {
 };
 
 /**
- * This type represent the item of a list audiences API request
+ * This type represent the item of a list audiences API request: the audience with its rule read back
+ * in words, which is what a picker shows. No usage count, that is one query per audience and belongs
+ * to [[GetAudienceResponse]]
  */
-export type ListAudiencesItem = AudienceResponse;
-
-/**
- * This type represent the response of a list audiences API request
- */
-export type ListAudiencesResponse = PagedListResponse<ListAudiencesItem>;
-
-/**
- * This type represent the usage of one key of an audience. A key with no entry is used by no content,
- * and is therefore the only kind of key that can be removed or renamed
- */
-export type AudienceKeyUsage = {
+export type ListAudiencesItem = AudienceResponse & {
     /**
-     * The key, or null for the rules that constrain the audience without naming any key - that is the
-     * ones that only fire when the audience is unknown
+     * The rule in words, so it reads without decoding a predicate
      */
-    key: string | null;
+    description: string;
     /**
-     * How many contents reference this key
+     * The mnemonic ids of the dimensions the rule depends on
      */
-    contents: number;
+    dimensions: string[];
 };
 
 /**
- * This type represent a content definition that declares an audience
+ * This type represent the response of a list audiences API request
  */
-export type DefinitionUsingAudience = {
-    /**
-     * The content definition unique id
-     */
-    id: ContentDefinitionId;
-    /**
-     * The content definition mnemonic id
-     */
-    mnemonicId: string;
-    /**
-     * The content definition name
-     */
-    name: string;
-};
+export type ListAudiencesResponse = PagedListResponse<ListAudiencesItem>;
 
 /**
  * This type represent the data needed to make a get audience API request
@@ -163,18 +193,20 @@ export type GetAudienceRequest = {
 };
 
 /**
- * This type represent the response of a get audience API request: the audience, plus the two things the
- * editor cannot decide without, which keys are in use and which definitions vary by this audience
+ * This type represent the response of a get audience API request: the audience, plus what the editor
+ * cannot derive on its own - the rule in words, the dimensions it depends on, and how many contents
+ * reference it, which is exactly the guard archiving enforces
  */
-export type GetAudienceResponse = AudienceResponse & {
+export type GetAudienceResponse = ListAudiencesItem & {
     /**
-     * One entry per key at least one content references. A key absent from this list is unused
+     * How much of the space depends on this audience
      */
-    keyUsage: AudienceKeyUsage[];
-    /**
-     * The content definitions declaring this audience
-     */
-    definitions: DefinitionUsingAudience[];
+    usage: {
+        /**
+         * How many contents reference this audience. Archiving is refused while this is not zero
+         */
+        contents: number;
+    };
 };
 
 /**
@@ -186,13 +218,14 @@ export type CreateAudienceRequest = {
      */
     name: string;
     /**
-     * The audience mnemonic id, matching [[AUDIENCE_NAME_PATTERN]]
+     * The audience mnemonic id, matching [[AUDIENCE_NAME_PATTERN]]. It cannot be changed afterwards
      */
     mnemonicId: string;
     /**
-     * The keys a visitor can hold for this audience, at least one, each key unique
+     * The rule over dimensions. Every dimension it names has to exist in the space and not be
+     * archived, and every key has to exist on its dimension and not be deprecated
      */
-    keys: AudienceKey[];
+    rule: AudienceRule;
 };
 
 /**
@@ -203,9 +236,8 @@ export type CreateAudienceResponse = AudienceResponse;
 /**
  * This type represent the data needed to make an update audience API request
  *
- * `keys` replaces the whole stored list, deprecation flags included. Adding keys and toggling
- * deprecation are always allowed, while removing or renaming a key is refused while a content still
- * references it. `mnemonicId` cannot be changed
+ * The rule may change freely even while contents reference the audience: the change reaching delivery
+ * on the next publish of any content that uses it is the point of naming an audience once
  */
 export type UpdateAudienceRequest = {
     /**
@@ -221,9 +253,9 @@ export type UpdateAudienceRequest = {
      */
     mnemonicId: string;
     /**
-     * The whole key list, replacing what is stored
+     * The rule, replacing what is stored
      */
-    keys: AudienceKey[];
+    rule: AudienceRule;
 };
 
 /**
@@ -240,7 +272,8 @@ export type ToggleArchivedAudienceRequest = {
      */
     id: AudienceId;
     /**
-     * This value represent the archive status to set in the specified audience
+     * This value represent the archive status to set in the specified audience. Archiving is refused
+     * with an `AudienceInUse` error while any content references the audience
      */
     archived: boolean;
 };
@@ -251,137 +284,74 @@ export type ToggleArchivedAudienceRequest = {
 export type ToggleArchivedAudienceResponse = AudienceResponse;
 
 /**
- * This type represent the condition of one rule on a single audience: the visitor's value for
- * [[audience]] has to be one of [[in]]
+ * Thin enum represent all audience rule violations error codes, reported by the create and update
+ * audience API requests through the `violations` of an `InvalidAudienceRule` error
  */
-export type AudiencePredicate = {
-    /**
-     * The mnemonic id of the audience this predicate constrains, which the field must declare
-     */
-    audience: string;
-    /**
-     * The keys of the audience that satisfy this predicate
-     */
-    in: string[];
-    /**
-     * Set this value to also satisfy the predicate when the audience was not provided at all
-     *
-     * Not-provided is not a key, so no list of keys can express it, and an enumeration would silently
-     * narrow the moment a key is added to the audience. A key that was provided but is not listed does
-     * not satisfy this flag: it falls through to the field's fallback
-     */
-    orUnset?: boolean;
-};
+export enum AudienceRuleViolationCodes {
+    ruleMissing = 'audienceRule.ruleMissing',
+    unknownShape = 'audienceRule.unknownShape',
+    groupIsNotAnArray = 'audienceRule.groupIsNotAnArray',
+    dimensionIsNotAString = 'audienceRule.dimensionIsNotAString',
+    inIsNotAnArray = 'audienceRule.inIsNotAnArray',
+    inIsEmpty = 'audienceRule.inIsEmpty',
+    keyIsNotAString = 'audienceRule.keyIsNotAString',
+    orUnsetIsNotABoolean = 'audienceRule.orUnsetIsNotABoolean',
+    dimensionNotFound = 'audienceRule.dimensionNotFound',
+    dimensionArchived = 'audienceRule.dimensionArchived',
+    dimensionKeyNotFound = 'audienceRule.dimensionKeyNotFound',
+    dimensionKeyDeprecated = 'audienceRule.dimensionKeyDeprecated'
+}
 
 /**
- * This type represent a condition satisfied when every child condition is satisfied
+ * This type represent one problem found in an audience rule, carrying the path of the offending node
  */
-export type AllAudiencePredicate = {
-    all: AudienceRuleCondition[];
-};
-
-/**
- * This type represent a condition satisfied when at least one child condition is satisfied
- */
-export type AnyAudiencePredicate = {
-    any: AudienceRuleCondition[];
-};
-
-/**
- * This type represent the condition of a rule
- *
- * The stored form is a tree so that new kinds of condition stay additive, but an editor only needs to
- * build an [[AllAudiencePredicate]] of one [[AudiencePredicate]] per audience: or within an audience, and
- * between audiences. An audience the condition does not mention is unconstrained, which is a different
- * thing from one listed with [[AudiencePredicate.orUnset]]
- */
-export type AudienceRuleCondition = AudiencePredicate | AllAudiencePredicate | AnyAudiencePredicate;
-
-/**
- * This type represent one rule of a personalized field: the condition, and the value to serve when it wins
- * @template T The type of the value served by the rule, which conforms to the field's `variantType`
- */
-export type PersonalizedRule<T = any> = {
+export type AudienceRuleViolation = {
     /**
-     * The rule id, unique in the field. Used for diagnostics only, matching never reads it
+     * The error code discriminator, one of [[AudienceRuleViolationCodes]]
      */
-    id?: string;
+    code: string;
     /**
-     * The condition under which this rule wins
+     * The path of the rejected node inside the rule, for instance `rule.all.0.in.1`
      */
-    when: AudienceRuleCondition;
+    path: string;
     /**
-     * The value served when this rule wins
+     * The dimension the node names, when the violation is about one
      */
-    value: T;
-};
-
-/**
- * This type represent the value a personalized field holds in a content payload: an ordered list of
- * rules, first match wins, and the fallback served when no rule matches
- *
- * The fallback is mandatory exactly when the field is required, which keeps the delivery contract of a
- * personalized field the same as any other field. Zero rules is legal: the field is then just its fallback
- * @template T The type of the served values, which conform to the field's `variantType`
- */
-export type PersonalizedFieldPayload<T = any> = {
-    /**
-     * The rules, in the order they are evaluated in
-     */
-    rules?: PersonalizedRule<T>[];
+    dimension?: string;
     /**
-     * The value served when no rule matches
+     * The key the node names, when the violation is about one
      */
-    fallback?: T;
-};
-
-/**
- * This type represent the visitor's value per audience, as the rule engine reads it. An audience missing
- * from the map, or set to `undefined`, means "not provided" - which is what
- * [[AudiencePredicate.orUnset]] answers
- */
-export type AudienceAssignment = {
-    [audienceMnemonicId: string]: string | undefined;
+    key?: string;
 };
 
 /**
- * The stand-in a coverage report uses for "a key none of the rules mention"
- *
- * Not a real key - it cannot be one, since keys match [[AUDIENCE_NAME_PATTERN]]. A rule only ever tests
- * membership in its own list, so every unmentioned key behaves identically and one case covers them
- * all, which is what keeps the analysis exact and small. [[CoverageReport.otherKeys]] says which real
- * keys it stood for
- */
-export const OTHER_KEY = '<any other key>';
-
-/**
- * This type represent how much of a rule list one rule actually serves
+ * This type represent how much of an analysed audience list one audience actually serves
  */
 export type RuleCoverage = {
     /**
-     * The position of the rule in the analysed list
+     * The position of the audience in the analysed list
      */
     index: number;
     /**
-     * The rule id, when it carries one
+     * The audience mnemonic id
      */
     id?: string;
     /**
-     * The condition in words, so a finding reads without decoding a predicate
+     * The rule in words, so a finding reads without decoding a predicate
      */
     condition: string;
     /**
-     * How many of the analysed assignments this rule wins. Zero means it can never serve anyone
+     * How many of the analysed assignments this audience wins. Zero means it can never serve anyone
      */
     wins: number;
 };
 
 /**
- * This type represent what an ordered rule list covers, worked out from the rules and the audiences'
- * keys alone - no request traffic is involved
+ * This type represent what an ordered list of audiences covers, worked out from their rules and the
+ * dimensions' keys alone - no request traffic is involved
  *
  * The findings are advisory and never validation violations: a gap is usually deliberate, that being
- * what a fallback is for, while an unreachable rule is almost always a mistake
+ * what a fallback is for, while an unreachable audience is almost always a mistake
  */
 export type CoverageReport = {
     /**
@@ -389,78 +359,89 @@ export type CoverageReport = {
      */
     combinations: number;
     /**
-     * One entry per analysed rule, in author order
+     * One entry per analysed audience, in the order they were sent, its `id` being the mnemonic id. An
+     * audience the space does not have has no rule to analyse and contributes no entry, so this can be
+     * shorter than the request
      */
     rules: RuleCoverage[];
     /**
-     * The rules that win nothing: shadowed by an earlier rule, or self-contradictory
+     * The audiences that win nothing: shadowed by an earlier one, or self-contradictory
      */
     unreachableRules: RuleCoverage[];
     /**
-     * The assignments no rule claims, so they reach the fallback. Capped at 25 entries, while
+     * The assignments no audience claims, so they reach the fallback. Capped at 25 entries, while
      * [[fallbackCount]] is the real total
      */
-    fallbackAssignments: AudienceAssignment[];
+    fallbackAssignments: DimensionAssignment[];
     /**
      * How many assignments reach the fallback, of [[combinations]]
      */
     fallbackCount: number;
     /**
-     * The audiences declared by the field but constrained by no rule, so they change nothing about what
-     * it serves
+     * What [[OTHER_KEY]] stood for, per dimension: the real unmentioned keys, capped at 10, with their
+     * total. Only the dimensions that needed the stand-in appear
      */
-    unusedAudiences: string[];
+    otherKeys: { [dimension: string]: { keys: string[]; total: number } };
     /**
-     * What [[OTHER_KEY]] stood for, per audience: the real unmentioned keys, capped at 10, with their
-     * total. Only the audiences that needed the stand-in appear
-     */
-    otherKeys: { [audience: string]: { keys: string[]; total: number } };
-    /**
-     * Set when the rules and their audiences were too large to enumerate. Everything else is then
+     * Set when the rules and their dimensions were too large to enumerate. Everything else is then
      * unpopulated rather than guessed, because a sampled "no gaps" is not a fact
      */
     notAnalysed?: { reason: 'tooManyCombinations'; combinations: number };
 };
 
 /**
- * This type represent one rule as the analyse rules API request takes it: the condition, and nothing
- * about what the rule serves. Coverage is decided by conditions only, so the values stay out of the
- * request - and a half written rule with no condition is analysed as one that matches nothing rather
- * than refused
+ * This type represent the data needed to make an analyse rules API request, which is what a
+ * personalized field's editor asks about the variants on screen, before anything is saved
+ *
+ * The rules and the dimensions' keys are read from the space, so a client sends the audiences and
+ * nothing else
  */
-export type PersonalizedRuleDraft = {
-    /**
-     * The rule id, when it carries one. Reported back on the finding, so a client can match a finding
-     * to the rule on screen without relying on the index
-     */
-    id?: string;
+export type AnalyseAudienceRulesRequest = {
     /**
-     * The condition under which this rule wins
+     * The audience mnemonic ids in the order the variants list them, at most 20. The order is the
+     * whole point: the first listed audience that matches wins, so one being unreachable is a
+     * consequence of what precedes it
      */
-    when?: AudienceRuleCondition;
+    audiences: string[];
 };
 
 /**
- * This type represent the data needed to make an analyse rules API request, which is what a field's
- * rule editor asks about the rules on screen, before anything is saved
- *
- * The keys of every audience are read from the space rather than taken from the request, so a client
- * never has to hold them or keep them current
+ * This type represent the response of an analyse rules API request
  */
-export type AnalyseAudienceRulesRequest = {
+export type AnalyseAudienceRulesResponse = CoverageReport;
+
+/**
+ * This type represent one variant of a personalized field: the audience served, and the value to
+ * serve it
+ * @template T The type of the served value, which conforms to the field's `variantType`
+ */
+export type PersonalizedVariant<T = any> = {
     /**
-     * The mnemonic ids of the audiences the field varies by, at most 20. The analysis is bounded by
-     * these, as the field's rules are
+     * The mnemonic id of the audience this variant serves
      */
-    audiences: string[];
+    audience: string;
     /**
-     * The rules in author order, at most 200. The order is the whole point: first match wins, so a rule
-     * being unreachable is a consequence of what precedes it
+     * The value served when this variant wins
      */
-    rules: PersonalizedRuleDraft[];
+    value: T;
 };
 
 /**
- * This type represent the response of an analyse rules API request
+ * This type represent the value a personalized field holds in a content payload: an ordered list of
+ * variants, the first whose audience matches the visitor wins, and the fallback served when none does
+ *
+ * The fallback is mandatory exactly when the field is required, which keeps the delivery contract of a
+ * personalized field the same as any other field. Zero variants is legal: the field is then just its
+ * fallback
+ * @template T The type of the served values, which conform to the field's `variantType`
  */
-export type AnalyseAudienceRulesResponse = CoverageReport;
+export type PersonalizedFieldPayload<T = any> = {
+    /**
+     * The variants, in the order they are evaluated in
+     */
+    variants?: PersonalizedVariant<T>[];
+    /**
+     * The value served when no variant's audience matches
+     */
+    fallback?: T;
+};

package/lib/api/Content.ts

@@ -404,9 +404,8 @@ export type ListContentsFilters = {
   translationStatus?: ContentTranslationStatus;
 
   /**
-   * This filter is used to search contents whose personalized fields have rules referencing the audiences
-   * inserted, as `audience` or `audience:key` tokens. A bare `audience` matches whichever key a content
-   * uses it with, and several tokens narrow the result like `tags` do
+   * This filter is used to search contents whose personalized fields have a variant serving one of the
+   * audience mnemonic ids inserted. Several of them narrow the result like `tags` do
    */
   audiences?: string[];
 };
@@ -847,16 +846,13 @@ export enum ContentFieldViolationCodes {
   textFieldValueIsNotAString = "textField.valueIsNotAString",
   textFieldBlankValueNotAllowed = "textField.blankValueNotAllowed",
   personalizedFieldValueIsNotPersonalized = "personalizedField.valueIsNotPersonalized",
-  personalizedFieldRulesIsNotAnArray = "personalizedField.rulesIsNotAnArray",
-  personalizedFieldRuleIsNotAnObject = "personalizedField.ruleIsNotAnObject",
-  personalizedFieldRuleConditionMissing = "personalizedField.ruleConditionMissing",
-  personalizedFieldDuplicateRuleId = "personalizedField.duplicateRuleId",
-  personalizedFieldAudienceNotDeclared = "personalizedField.audienceNotDeclared",
-  personalizedFieldFallbackRequired = "personalizedField.fallbackRequired",
+  personalizedFieldVariantsIsNotAnArray = "personalizedField.variantsIsNotAnArray",
+  personalizedFieldVariantIsNotAnObject = "personalizedField.variantIsNotAnObject",
+  personalizedFieldAudienceMissing = "personalizedField.audienceMissing",
   personalizedFieldAudienceNotFound = "personalizedField.audienceNotFound",
   personalizedFieldAudienceArchived = "personalizedField.audienceArchived",
-  personalizedFieldAudienceKeyNotFound = "personalizedField.audienceKeyNotFound",
-  personalizedFieldAudienceKeyDeprecated = "personalizedField.audienceKeyDeprecated",
+  personalizedFieldDuplicateAudience = "personalizedField.duplicateAudience",
+  personalizedFieldFallbackRequired = "personalizedField.fallbackRequired",
 }
 
 /**
@@ -913,7 +909,8 @@ export type AnalysePersonalizedRulesRequest = {
 };
 
 /**
- * This type represent the coverage of one personalized field of a content
+ * This type represent the coverage of one personalized field of a content, that is what the audiences
+ * of its variants cover
  */
 export type PersonalizedFieldCoverage = CoverageReport & {
   /**

package/lib/api/ContentDefinition.ts

@@ -189,12 +189,6 @@ export type ContentDefinitionResponse = {
      * Valued with paths to each array or null if definition is legacy
      */
     trackableArrayFields?: ArrayField[] | null;
-
-    /**
-     * The mnemonic ids of the audiences this definition's personalized fields vary by
-     * Derived from the schema on every save, never assigned by the client
-     */
-    audiences?: string[];
 };
 
 /**
@@ -287,15 +281,6 @@ export type ContentDefinitionSchemaErrors = {
      * This attribute represents an error if the language of the schema is not a valid string
      */
     lang?: string;
-    /**
-     * This attribute represents all the error that occurs inside the audiences declaration of the
-     * definition schema object
-     *
-     * - The value is a string if the audiences value is not in the expected format
-     * - The value is a list of AttributeViolation, one per declared audience that does not exist in the
-     *   space or is archived
-     */
-    audiences?: string | AttributeViolation[];
 };
 
 /**
@@ -431,9 +416,5 @@ export enum SchemaFieldViolationCodes {
     translatableNotAllowed = 'translatableNotAllowed',
     invalidEnumValue = 'invalidEnumValue',
     compactCannotBeNested = 'compactCannotBeNested',
-    audienceTypeNotAllowed = 'audienceTypeNotAllowed',
-    audienceNameNotFound = 'audienceNameNotFound',
-    audienceArchived = 'audienceArchived',
-    audienceNotDeclaredByDefinition = 'audienceNotDeclaredByDefinition',
-    duplicateAudienceName = 'duplicateAudienceName'
+    variantTypeNotAllowed = 'variantTypeNotAllowed'
 }