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

package/dist/api/ContentDefinitionSchema.d.ts

@@ -20,7 +20,7 @@ export declare enum SchemaTypeIds {
     ARRAY = "array",
     SLUG = "slug",
     MEDIA = "media",
-    SEGMENTED = "segmented"
+    PERSONALIZED = "personalized"
 }
 /**
  * This enum represent al possible long text sub types
@@ -49,13 +49,13 @@ export type ContentDefinitionSchema = {
      */
     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
+     * The audiences this definition depends on, chosen by the author. Every one has to exist in the
+     * space and not be archived, and a personalized field may only vary by audiences 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
+     * Optional: a definition that declares none simply cannot hold a personalized field
      */
-    segments?: string[];
+    audiences?: string[];
 };
 /**
  * This type represent the model of the attribute fragments in a content definition schema
@@ -303,13 +303,13 @@ export type OneLinkedContentOfConstraints = {
     linkType?: LinkType;
 };
 /**
- * This type represent what every value of a segmented field holds: one descriptor for the whole field,
+ * This type represent what every value of a personalized field holds: one descriptor for the whole field,
  * so the rules 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;
 } | {
@@ -317,28 +317,28 @@ export type SegmentVariantType = {
     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
+ * A personalized 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
+ * fallback - see [[PersonalizedFieldPayload]] - so no combination has to be pre-declared here and two
  * contents of the same definition may carry entirely different rule sets
  */
-export type SegmentedFieldConstraints = {
+export type PersonalizedFieldConstraints = {
     /**
-     * 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
+     * The mnemonic ids of the audiences this field varies by, which must be among the ones the
+     * definition declares in [[ContentDefinitionSchema.audiences]]. Only the declaration is checked
+     * against the space, so an audience 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
+     * audience it constrains
      */
-    segments: string[];
+    audiences: string[];
     /**
      * The shape every rule value and the fallback conform to
      */
-    variantType: SegmentVariantType;
+    variantType: PersonalizedVariantType;
 };
 /**
  * This type represent the model of an array field constraints
@@ -492,9 +492,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
  * This type is indexable and translatable by default
@@ -520,7 +520,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
  */

package/dist/api/ContentDefinitionSchema.js

@@ -23,7 +23,7 @@ var SchemaTypeIds;
     SchemaTypeIds["ARRAY"] = "array";
     SchemaTypeIds["SLUG"] = "slug";
     SchemaTypeIds["MEDIA"] = "media";
-    SchemaTypeIds["SEGMENTED"] = "segmented";
+    SchemaTypeIds["PERSONALIZED"] = "personalized";
 })(SchemaTypeIds || (exports.SchemaTypeIds = SchemaTypeIds = {}));
 /**
  * This enum represent al possible long text sub types

package/dist/api/index.d.ts

@@ -12,7 +12,7 @@ export * from './Invites';
 export * from './MediaGallery';
 export * from './PublishedContent';
 export * from './PublishingRequest';
-export * from './Segment';
+export * from './Audience';
 export * from './Space';
 export * from './Subscription';
 export * from './UnpublishRequest';

package/dist/api/index.js

@@ -28,7 +28,7 @@ __exportStar(require("./Invites"), exports);
 __exportStar(require("./MediaGallery"), exports);
 __exportStar(require("./PublishedContent"), exports);
 __exportStar(require("./PublishingRequest"), exports);
-__exportStar(require("./Segment"), exports);
+__exportStar(require("./Audience"), exports);
 __exportStar(require("./Space"), exports);
 __exportStar(require("./Subscription"), exports);
 __exportStar(require("./UnpublishRequest"), exports);

package/lib/api/Audience.ts

@@ -0,0 +1,466 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+import { ContentDefinitionId } from './ContentDefinition';
+
+/**
+ * The audience unique id
+ */
+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
+ */
+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
+ */
+export type AudienceKey = {
+    /**
+     * The key, matching [[AUDIENCE_NAME_PATTERN]]
+     */
+    key: string;
+    /**
+     * A deprecated key cannot be referenced by new content rules, while every rule already written
+     * keeps resolving. The flag toggles both ways
+     */
+    deprecated?: boolean;
+};
+
+/**
+ * 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
+ *
+ * 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
+ */
+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 keys a visitor can hold for this audience, each carrying its own deprecation state
+     */
+    keys: AudienceKey[];
+    /**
+     * 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
+ */
+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 = {
+    /**
+     * 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
+     */
+    key: string | null;
+    /**
+     * How many contents reference this key
+     */
+    contents: number;
+};
+
+/**
+ * This type represent a content definition that declares an audience
+ */
+export type DefinitionUsingAudience = {
+    /**
+     * The content definition unique id
+     */
+    id: ContentDefinitionId;
+    /**
+     * The content definition mnemonic id
+     */
+    mnemonicId: string;
+    /**
+     * The content definition name
+     */
+    name: string;
+};
+
+/**
+ * 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 the two things the
+ * editor cannot decide without, which keys are in use and which definitions vary by this audience
+ */
+export type GetAudienceResponse = AudienceResponse & {
+    /**
+     * One entry per key at least one content references. A key absent from this list is unused
+     */
+    keyUsage: AudienceKeyUsage[];
+    /**
+     * The content definitions declaring this audience
+     */
+    definitions: DefinitionUsingAudience[];
+};
+
+/**
+ * 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]]
+     */
+    mnemonicId: string;
+    /**
+     * The keys a visitor can hold for this audience, at least one, each key unique
+     */
+    keys: AudienceKey[];
+};
+
+/**
+ * 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
+ *
+ * `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
+ */
+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 whole key list, replacing what is stored
+     */
+    keys: AudienceKey[];
+};
+
+/**
+ * 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
+     */
+    archived: boolean;
+};
+
+/**
+ * This type represent the response of a toggle archived audience API request
+ */
+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]]
+ */
+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;
+};
+
+/**
+ * This type represent a condition satisfied when every child condition is satisfied
+ */
+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> = {
+    /**
+     * The rule id, unique in the field. Used for diagnostics only, matching never reads it
+     */
+    id?: string;
+    /**
+     * The condition under which this rule wins
+     */
+    when: AudienceRuleCondition;
+    /**
+     * The value served when this rule wins
+     */
+    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>[];
+    /**
+     * The value served when no rule matches
+     */
+    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;
+};
+
+/**
+ * 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
+ */
+export type RuleCoverage = {
+    /**
+     * The position of the rule in the analysed list
+     */
+    index: number;
+    /**
+     * The rule id, when it carries one
+     */
+    id?: string;
+    /**
+     * The condition 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
+     */
+    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
+ *
+ * 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
+ */
+export type CoverageReport = {
+    /**
+     * How many assignments were evaluated, after collapsing the keys no rule mentions
+     */
+    combinations: number;
+    /**
+     * One entry per analysed rule, in author order
+     */
+    rules: RuleCoverage[];
+    /**
+     * The rules that win nothing: shadowed by an earlier rule, or self-contradictory
+     */
+    unreachableRules: RuleCoverage[];
+    /**
+     * The assignments no rule claims, so they reach the fallback. Capped at 25 entries, while
+     * [[fallbackCount]] is the real total
+     */
+    fallbackAssignments: AudienceAssignment[];
+    /**
+     * 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
+     */
+    unusedAudiences: string[];
+    /**
+     * 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
+     * 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
+ */
+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;
+    /**
+     * The condition under which this rule wins
+     */
+    when?: AudienceRuleCondition;
+};
+
+/**
+ * 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
+ */
+export type AnalyseAudienceRulesRequest = {
+    /**
+     * 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
+     */
+    audiences: 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
+     */
+    rules: PersonalizedRuleDraft[];
+};
+
+/**
+ * This type represent the response of an analyse rules API request
+ */
+export type AnalyseAudienceRulesResponse = CoverageReport;

package/lib/api/Content.ts

@@ -14,6 +14,7 @@ import {
   ContentTranslation,
   ContentTranslationStatus,
 } from "./ContentTranslation";
+import { CoverageReport } from "./Audience";
 
 /**
  * This type represent the content unique id type
@@ -403,11 +404,11 @@ 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
+   * 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
    */
-  segments?: string[];
+  audiences?: string[];
 };
 
 /**
@@ -845,17 +846,17 @@ 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",
+  personalizedFieldRulesIsNotAnArray = "personalizedField.rulesIsNotAnArray",
+  personalizedFieldRuleIsNotAnObject = "personalizedField.ruleIsNotAnObject",
+  personalizedFieldRuleConditionMissing = "personalizedField.ruleConditionMissing",
+  personalizedFieldDuplicateRuleId = "personalizedField.duplicateRuleId",
+  personalizedFieldAudienceNotDeclared = "personalizedField.audienceNotDeclared",
+  personalizedFieldFallbackRequired = "personalizedField.fallbackRequired",
+  personalizedFieldAudienceNotFound = "personalizedField.audienceNotFound",
+  personalizedFieldAudienceArchived = "personalizedField.audienceArchived",
+  personalizedFieldAudienceKeyNotFound = "personalizedField.audienceKeyNotFound",
+  personalizedFieldAudienceKeyDeprecated = "personalizedField.audienceKeyDeprecated",
 }
 
 /**
@@ -900,3 +901,39 @@ export type ToggleContentTranslationsRequest = {
 };
 
 export type ToggleContentTranslationsResponse = ContentResponse;
+
+/**
+ * This type represent the data needed to make an analyse personalized rules API request
+ */
+export type AnalysePersonalizedRulesRequest = {
+  /**
+   * Id of the content whose personalized fields have to be analysed
+   */
+  contentId: ContentId;
+};
+
+/**
+ * This type represent the coverage of one personalized field of a content
+ */
+export type PersonalizedFieldCoverage = CoverageReport & {
+  /**
+   * Where the field sits in the payload
+   */
+  path: string;
+  /**
+   * Whether the field carries a fallback. An optional field without one resolves to nothing for the
+   * assignments in [[CoverageReport.fallbackAssignments]], which is worth knowing
+   */
+  hasFallback: boolean;
+};
+
+/**
+ * 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 AnalysePersonalizedRulesResponse = {
+  /**
+   * One entry per personalized field found in the content payload
+   */
+  fields: PersonalizedFieldCoverage[];
+};