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

package/lib/api/Audience.ts

@@ -0,0 +1,447 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import { DimensionAssignment } from './Dimension';
+
+/**
+ * The audience unique id
+ */
+export type AudienceId = number;
+
+/**
+ * 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 the condition of an audience rule on a single dimension: the visitor's value for
+ * [[dimension]] has to be one of [[in]]
+ */
+export type DimensionPredicate = {
+    /**
+     * The mnemonic id of the dimension this predicate constrains
+     */
+    dimension: string;
+    /**
+     * The keys of the dimension that satisfy this predicate, at least one
+     */
+    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 named rule over dimensions -
+ * "authenticated users with a silver card" - written once and referenced by mnemonicId from every
+ * content that wants 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 = {
+    /**
+     * The audience unique id
+     */
+    id: AudienceId;
+    /**
+     * The audience name
+     */
+    name: string;
+    /**
+     * The audience mnemonic id, matching [[AUDIENCE_NAME_PATTERN]]
+     */
+    mnemonicId: string;
+    /**
+     * 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
+     */
+    usedDimensionKeys: DimensionKeyReference[];
+    /**
+     * The archived status of the audience
+     */
+    archived: boolean;
+    /**
+     * The archive date of the audience
+     */
+    archivedDate: Date | null;
+    /**
+     * The audience creation date
+     */
+    createdDate: Date;
+    /**
+     * The audience last modified date
+     */
+    lastModifiedDate: Date;
+    /**
+     * The audience author, resolved by `list` only
+     */
+    author?: AuthorResponse;
+    /**
+     * The audience last modified author, resolved by every endpoint but `get`
+     */
+    latestContributor?: AuthorResponse;
+};
+
+/**
+ * This type represent all possible filters used to retrieve a list of audience
+ */
+export type ListAudiencesFilters = {
+    /**
+     * This filter is used to retrieve archived or not archived audiences. Defaults to not archived
+     */
+    archived?: boolean;
+};
+
+/**
+ * This type represent the data needed to make a list audiences API request
+ */
+export type ListAudiencesRequest = {
+    /**
+     * The number of audiences to skip (this value is used for pagination)
+     */
+    skip?: number;
+    /**
+     * The number of audiences to take (this value is used for pagination), at most 100
+     */
+    take?: number;
+    /**
+     * The data used to filter the list of audiences
+     */
+    filters?: ListAudiencesFilters;
+};
+
+/**
+ * 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 & {
+    /**
+     * The rule in words, so it reads without decoding a predicate
+     */
+    description: string;
+    /**
+     * The mnemonic ids of the dimensions the rule depends on
+     */
+    dimensions: string[];
+};
+
+/**
+ * This type represent the response of a list audiences API request
+ */
+export type ListAudiencesResponse = PagedListResponse<ListAudiencesItem>;
+
+/**
+ * This type represent the data needed to make a get audience API request
+ */
+export type GetAudienceRequest = {
+    /**
+     * The unique audience id to retrieve
+     */
+    id: AudienceId;
+};
+
+/**
+ * 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 = ListAudiencesItem & {
+    /**
+     * How much of the space depends on this audience
+     */
+    usage: {
+        /**
+         * How many contents reference this audience. Archiving is refused while this is not zero
+         */
+        contents: number;
+    };
+};
+
+/**
+ * This type represent the data needed to make a create audience API request
+ */
+export type CreateAudienceRequest = {
+    /**
+     * The audience name
+     */
+    name: string;
+    /**
+     * The audience mnemonic id, matching [[AUDIENCE_NAME_PATTERN]]. It cannot be changed afterwards
+     */
+    mnemonicId: string;
+    /**
+     * 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
+     */
+    rule: AudienceRule;
+};
+
+/**
+ * This type represent the response of a create audience API request
+ */
+export type CreateAudienceResponse = AudienceResponse;
+
+/**
+ * This type represent the data needed to make an update audience API request
+ *
+ * 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 = {
+    /**
+     * The audience unique id
+     */
+    id: AudienceId;
+    /**
+     * The audience name to update
+     */
+    name: string;
+    /**
+     * The audience mnemonic id, which must be the stored one
+     */
+    mnemonicId: string;
+    /**
+     * The rule, replacing what is stored
+     */
+    rule: AudienceRule;
+};
+
+/**
+ * This type represent the response of an update audience API request
+ */
+export type UpdateAudienceResponse = AudienceResponse;
+
+/**
+ * This type represent the data needed to make a toggle archived audience API request
+ */
+export type ToggleArchivedAudienceRequest = {
+    /**
+     * The audience unique id
+     */
+    id: AudienceId;
+    /**
+     * 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;
+};
+
+/**
+ * This type represent the response of a toggle archived audience API request
+ */
+export type ToggleArchivedAudienceResponse = AudienceResponse;
+
+/**
+ * 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 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 one problem found in an audience rule, carrying the path of the offending node
+ */
+export type AudienceRuleViolation = {
+    /**
+     * The error code discriminator, one of [[AudienceRuleViolationCodes]]
+     */
+    code: string;
+    /**
+     * The path of the rejected node inside the rule, for instance `rule.all.0.in.1`
+     */
+    path: string;
+    /**
+     * The dimension the node names, when the violation is about one
+     */
+    dimension?: string;
+    /**
+     * The key the node names, when the violation is about one
+     */
+    key?: string;
+};
+
+/**
+ * This type represent how much of an analysed audience list one audience actually serves
+ */
+export type RuleCoverage = {
+    /**
+     * The position of the audience in the analysed list
+     */
+    index: number;
+    /**
+     * The audience mnemonic id
+     */
+    id?: string;
+    /**
+     * The rule in words, so a finding reads without decoding a predicate
+     */
+    condition: string;
+    /**
+     * How many of the analysed assignments this audience wins. Zero means it can never serve anyone
+     */
+    wins: number;
+};
+
+/**
+ * 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 audience is almost always a mistake
+ */
+export type CoverageReport = {
+    /**
+     * How many assignments were evaluated, after collapsing the keys no rule mentions
+     */
+    combinations: number;
+    /**
+     * 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 audiences that win nothing: shadowed by an earlier one, or self-contradictory
+     */
+    unreachableRules: RuleCoverage[];
+    /**
+     * The assignments no audience claims, so they reach the fallback. Capped at 25 entries, while
+     * [[fallbackCount]] is the real total
+     */
+    fallbackAssignments: DimensionAssignment[];
+    /**
+     * How many assignments reach the fallback, of [[combinations]]
+     */
+    fallbackCount: number;
+    /**
+     * 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
+     */
+    otherKeys: { [dimension: string]: { keys: string[]; total: number } };
+    /**
+     * 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 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 AnalyseAudienceRulesRequest = {
+    /**
+     * 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
+     */
+    audiences: string[];
+};
+
+/**
+ * This type represent the response of an analyse rules API request
+ */
+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 id of the audience this variant serves
+     */
+    audience: string;
+    /**
+     * The value served when this variant wins
+     */
+    value: T;
+};
+
+/**
+ * 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 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

@@ -14,7 +14,7 @@ import {
   ContentTranslation,
   ContentTranslationStatus,
 } from "./ContentTranslation";
-import { CoverageReport } from "./Segment";
+import { CoverageReport } from "./Audience";
 
 /**
  * This type represent the content unique id type
@@ -404,11 +404,10 @@ export type ListContentsFilters = {
   translationStatus?: ContentTranslationStatus;
 
   /**
-   * This filter is used to search contents whose segmented fields have rules referencing the segments
-   * inserted, as `segment` or `segment:key` tokens. A bare `segment` 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
    */
-  segments?: string[];
+  audiences?: string[];
 };
 
 /**
@@ -846,17 +845,14 @@ export enum ContentFieldViolationCodes {
   textFieldValueMissingInListOfValue = "textField.valueMissingInListOfValue",
   textFieldValueIsNotAString = "textField.valueIsNotAString",
   textFieldBlankValueNotAllowed = "textField.blankValueNotAllowed",
-  segmentedFieldValueIsNotSegmented = "segmentedField.valueIsNotSegmented",
-  segmentedFieldRulesIsNotAnArray = "segmentedField.rulesIsNotAnArray",
-  segmentedFieldRuleIsNotAnObject = "segmentedField.ruleIsNotAnObject",
-  segmentedFieldRuleConditionMissing = "segmentedField.ruleConditionMissing",
-  segmentedFieldDuplicateRuleId = "segmentedField.duplicateRuleId",
-  segmentedFieldSegmentNotDeclared = "segmentedField.segmentNotDeclared",
-  segmentedFieldFallbackRequired = "segmentedField.fallbackRequired",
-  segmentedFieldSegmentNotFound = "segmentedField.segmentNotFound",
-  segmentedFieldSegmentArchived = "segmentedField.segmentArchived",
-  segmentedFieldSegmentKeyNotFound = "segmentedField.segmentKeyNotFound",
-  segmentedFieldSegmentKeyDeprecated = "segmentedField.segmentKeyDeprecated",
+  personalizedFieldValueIsNotPersonalized = "personalizedField.valueIsNotPersonalized",
+  personalizedFieldVariantsIsNotAnArray = "personalizedField.variantsIsNotAnArray",
+  personalizedFieldVariantIsNotAnObject = "personalizedField.variantIsNotAnObject",
+  personalizedFieldAudienceMissing = "personalizedField.audienceMissing",
+  personalizedFieldAudienceNotFound = "personalizedField.audienceNotFound",
+  personalizedFieldAudienceArchived = "personalizedField.audienceArchived",
+  personalizedFieldDuplicateAudience = "personalizedField.duplicateAudience",
+  personalizedFieldFallbackRequired = "personalizedField.fallbackRequired",
 }
 
 /**
@@ -903,19 +899,20 @@ export type ToggleContentTranslationsRequest = {
 export type ToggleContentTranslationsResponse = ContentResponse;
 
 /**
- * This type represent the data needed to make an analyse segmented rules API request
+ * This type represent the data needed to make an analyse personalized rules API request
  */
-export type AnalyseSegmentedRulesRequest = {
+export type AnalysePersonalizedRulesRequest = {
   /**
-   * Id of the content whose segmented fields have to be analysed
+   * Id of the content whose personalized fields have to be analysed
    */
   contentId: ContentId;
 };
 
 /**
- * This type represent the coverage of one segmented 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 SegmentedFieldCoverage = CoverageReport & {
+export type PersonalizedFieldCoverage = CoverageReport & {
   /**
    * Where the field sits in the payload
    */
@@ -928,12 +925,12 @@ export type SegmentedFieldCoverage = CoverageReport & {
 };
 
 /**
- * This type represent the response of an analyse segmented rules API request: one report per
- * segmented field of the content, empty when it has none
+ * This type represent the response of an analyse personalized rules API request: one report per
+ * personalized field of the content, empty when it has none
  */
-export type AnalyseSegmentedRulesResponse = {
+export type AnalysePersonalizedRulesResponse = {
   /**
-   * One entry per segmented field found in the content payload
+   * One entry per personalized field found in the content payload
    */
-  fields: SegmentedFieldCoverage[];
+  fields: PersonalizedFieldCoverage[];
 };

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 segments this definition's segmented fields vary by
-     * Derived from the schema on every save, never assigned by the client
-     */
-    segments?: 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 segments declaration of the
-     * definition schema object
-     *
-     * - The value is a string if the segments value is not in the expected format
-     * - The value is a list of AttributeViolation, one per declared segment that does not exist in the
-     *   space or is archived
-     */
-    segments?: string | AttributeViolation[];
 };
 
 /**
@@ -431,9 +416,5 @@ export enum SchemaFieldViolationCodes {
     translatableNotAllowed = 'translatableNotAllowed',
     invalidEnumValue = 'invalidEnumValue',
     compactCannotBeNested = 'compactCannotBeNested',
-    segmentTypeNotAllowed = 'segmentTypeNotAllowed',
-    segmentNameNotFound = 'segmentNameNotFound',
-    segmentArchived = 'segmentArchived',
-    segmentNotDeclaredByDefinition = 'segmentNotDeclaredByDefinition',
-    duplicateSegmentName = 'duplicateSegmentName'
+    variantTypeNotAllowed = 'variantTypeNotAllowed'
 }

package/lib/api/ContentDefinitionSchema.ts

@@ -21,7 +21,7 @@ export enum SchemaTypeIds {
     ARRAY = 'array',
     SLUG = 'slug',
     MEDIA = 'media',
-    SEGMENTED = 'segmented',
+    PERSONALIZED = 'personalized',
 }
 
 /**
@@ -51,14 +51,6 @@ export type ContentDefinitionSchema = {
      * A Fragment is a custom field defined by the user and can be used internally in the definition
      */
     fragments: FragmentsTable;
-    /**
-     * The segments this definition depends on, chosen by the author. Every one has to exist in the
-     * space and not be archived, and a segmented field may only vary by segments named here, so this
-     * is what scopes a definition and gives the field editor a short list to offer
-     *
-     * Optional: a definition that declares none simply cannot hold a segmented field
-     */
-    segments?: string[];
 };
 
 /**
@@ -329,39 +321,29 @@ export type OneLinkedContentOfConstraints = {
 };
 
 /**
- * This type represent what every value of a segmented field holds: one descriptor for the whole field,
- * so the rules and the fallback cannot differ in type
+ * This type represent what every value of a personalized field holds: one descriptor for the whole field,
+ * so the variants and the fallback cannot differ in type
  *
  * Only the two `one...Of` forms are admitted: `fragment` and `linked-content` are each the
  * single-target special case of one of them, carrying an identical payload value
  */
-export type SegmentVariantType =
+export type PersonalizedVariantType =
     | { type: SchemaTypeIds.ONE_FRAGMENT_OF; constraints: OneFragmentOfConstraints; }
     | { type: SchemaTypeIds.ONE_LINKED_CONTENT_OF; constraints: OneLinkedContentOfConstraints; };
 
 /**
- * This type represent the model of a segmented field constraints
+ * This type represent the model of a personalized field constraints
  *
- * A segmented field declares only *what varies* and *what shape the values have*. Which conditions
- * exist and what each of them serves is authored per content, as an ordered list of rules plus a
- * fallback - see [[SegmentedFieldPayload]] - so no combination has to be pre-declared here and two
- * contents of the same definition may carry entirely different rule sets
+ * A personalized field says only *what shape the values have*. Which audiences it serves is authored
+ * per content, as an ordered list of variants plus a fallback - see [[PersonalizedFieldPayload]] - so
+ * nothing has to be pre-declared here and two contents of the same definition may target entirely
+ * different audiences
  */
-export type SegmentedFieldConstraints = {
-    /**
-     * The mnemonic ids of the segments this field varies by, which must be among the ones the
-     * definition declares in [[ContentDefinitionSchema.segments]]. Only the declaration is checked
-     * against the space, so a segment that does not exist is one error on the definition rather than
-     * one on every field that reached for it
-     *
-     * Declaration order carries no meaning: a rule wins by being first in the content, not by which
-     * segment it constrains
-     */
-    segments: string[];
+export type PersonalizedFieldConstraints = {
     /**
-     * The shape every rule value and the fallback conform to
+     * The shape every variant value and the fallback conform to
      */
-    variantType: SegmentVariantType;
+    variantType: PersonalizedVariantType;
 };
 
 /**
@@ -529,9 +511,9 @@ export type OneFragmentOfSchemaType = SchemaType<SchemaTypeIds.ONE_FRAGMENT_OF,
 export type OneLinkedContentOfSchemaType = IndexableSchemaType<SchemaTypeIds.ONE_LINKED_CONTENT_OF, OneLinkedContentOfConstraints>;
 
 /**
- * This type represent a segmented field schema type
+ * This type represent a personalized field schema type
  */
-export type SegmentedSchemaType = SchemaType<SchemaTypeIds.SEGMENTED, SegmentedFieldConstraints>;
+export type PersonalizedSchemaType = SchemaType<SchemaTypeIds.PERSONALIZED, PersonalizedFieldConstraints>;
 
 /**
  * Slug schema type
@@ -565,7 +547,7 @@ export type TranslatableSchemaTypes = NumberSchemaType | TextSchemaType | LongTe
 /**
  * This type group all the schema types of a content definition that are not indexable
  */
-export type PlainSchemaTypes = DateSchemaType | FragmentSchemaType | OneFragmentOfSchemaType | SlugSchemaType | SegmentedSchemaType;
+export type PlainSchemaTypes = DateSchemaType | FragmentSchemaType | OneFragmentOfSchemaType | SlugSchemaType | PersonalizedSchemaType;
 
 /**
  * This type group all schema types of a content definition