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

package/lib/api/Segment.ts

@@ -1,466 +0,0 @@
-import { AuthorResponse } from './Author';
-import { PagedListResponse } from './common';
-import { ContentDefinitionId } from './ContentDefinition';
-
-/**
- * The segment unique id
- */
-export type SegmentId = number;
-
-/**
- * A segment'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 `segments` query param and are compared against strings a client supplies
- */
-export const SEGMENT_NAME_PATTERN = /^[a-z0-9_-]+$/;
-
-/**
- * This type represent one key of a segment, that is one of the values a visitor can have for it
- */
-export type SegmentKey = {
-    /**
-     * The key, matching [[SEGMENT_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 a segment, 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 a segment by mnemonicId and key inside their rules, and definitions by
- * mnemonicId, so segments are archived and never deleted, and a key can only be removed or renamed
- * while no content references it
- */
-export type SegmentResponse = {
-    /**
-     * The segment unique id
-     */
-    id: SegmentId;
-    /**
-     * The segment name
-     */
-    name: string;
-    /**
-     * The segment mnemonic id, matching [[SEGMENT_NAME_PATTERN]]
-     */
-    mnemonicId: string;
-    /**
-     * The keys a visitor can hold for this segment, each carrying its own deprecation state
-     */
-    keys: SegmentKey[];
-    /**
-     * The archived status of the segment
-     */
-    archived: boolean;
-    /**
-     * The archive date of the segment
-     */
-    archivedDate: Date | null;
-    /**
-     * The segment creation date
-     */
-    createdDate: Date;
-    /**
-     * The segment last modified date
-     */
-    lastModifiedDate: Date;
-    /**
-     * The segment author, resolved by `list` only
-     */
-    author?: AuthorResponse;
-    /**
-     * The segment last modified author, resolved by every endpoint but `get`
-     */
-    latestContributor?: AuthorResponse;
-};
-
-/**
- * This type represent all possible filters used to retrieve a list of segment
- */
-export type ListSegmentsFilters = {
-    /**
-     * This filter is used to retrieve archived or not archived segments. Defaults to not archived
-     */
-    archived?: boolean;
-};
-
-/**
- * This type represent the data needed to make a list segments API request
- */
-export type ListSegmentsRequest = {
-    /**
-     * The number of segments to skip (this value is used for pagination)
-     */
-    skip?: number;
-    /**
-     * The number of segments to take (this value is used for pagination), at most 100
-     */
-    take?: number;
-    /**
-     * The data used to filter the list of segments
-     */
-    filters?: ListSegmentsFilters;
-};
-
-/**
- * This type represent the item of a list segments API request
- */
-export type ListSegmentsItem = SegmentResponse;
-
-/**
- * This type represent the response of a list segments API request
- */
-export type ListSegmentsResponse = PagedListResponse<ListSegmentsItem>;
-
-/**
- * This type represent the usage of one key of a segment. 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 SegmentKeyUsage = {
-    /**
-     * The key, or null for the rules that constrain the segment without naming any key - that is the
-     * ones that only fire when the segment is unknown
-     */
-    key: string | null;
-    /**
-     * How many contents reference this key
-     */
-    contents: number;
-};
-
-/**
- * This type represent a content definition that declares a segment
- */
-export type DefinitionUsingSegment = {
-    /**
-     * 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 segment API request
- */
-export type GetSegmentRequest = {
-    /**
-     * The unique segment id to retrieve
-     */
-    id: SegmentId;
-};
-
-/**
- * This type represent the response of a get segment API request: the segment, plus the two things the
- * editor cannot decide without, which keys are in use and which definitions vary by this segment
- */
-export type GetSegmentResponse = SegmentResponse & {
-    /**
-     * One entry per key at least one content references. A key absent from this list is unused
-     */
-    keyUsage: SegmentKeyUsage[];
-    /**
-     * The content definitions declaring this segment
-     */
-    definitions: DefinitionUsingSegment[];
-};
-
-/**
- * This type represent the data needed to make a create segment API request
- */
-export type CreateSegmentRequest = {
-    /**
-     * The segment name
-     */
-    name: string;
-    /**
-     * The segment mnemonic id, matching [[SEGMENT_NAME_PATTERN]]
-     */
-    mnemonicId: string;
-    /**
-     * The keys a visitor can hold for this segment, at least one, each key unique
-     */
-    keys: SegmentKey[];
-};
-
-/**
- * This type represent the response of a create segment API request
- */
-export type CreateSegmentResponse = SegmentResponse;
-
-/**
- * This type represent the data needed to make an update segment 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 UpdateSegmentRequest = {
-    /**
-     * The segment unique id
-     */
-    id: SegmentId;
-    /**
-     * The segment name to update
-     */
-    name: string;
-    /**
-     * The segment mnemonic id, which must be the stored one
-     */
-    mnemonicId: string;
-    /**
-     * The whole key list, replacing what is stored
-     */
-    keys: SegmentKey[];
-};
-
-/**
- * This type represent the response of an update segment API request
- */
-export type UpdateSegmentResponse = SegmentResponse;
-
-/**
- * This type represent the data needed to make a toggle archived segment API request
- */
-export type ToggleArchivedSegmentRequest = {
-    /**
-     * The segment unique id
-     */
-    id: SegmentId;
-    /**
-     * This value represent the archive status to set in the specified segment
-     */
-    archived: boolean;
-};
-
-/**
- * This type represent the response of a toggle archived segment API request
- */
-export type ToggleArchivedSegmentResponse = SegmentResponse;
-
-/**
- * This type represent the condition of one rule on a single segment: the visitor's value for
- * [[segment]] has to be one of [[in]]
- */
-export type SegmentPredicate = {
-    /**
-     * The mnemonic id of the segment this predicate constrains, which the field must declare
-     */
-    segment: string;
-    /**
-     * The keys of the segment that satisfy this predicate
-     */
-    in: string[];
-    /**
-     * Set this value to also satisfy the predicate when the segment 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 segment. 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 AllSegmentPredicate = {
-    all: SegmentRuleCondition[];
-};
-
-/**
- * This type represent a condition satisfied when at least one child condition is satisfied
- */
-export type AnySegmentPredicate = {
-    any: SegmentRuleCondition[];
-};
-
-/**
- * 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 [[AllSegmentPredicate]] of one [[SegmentPredicate]] per segment: or within a segment, and
- * between segments. A segment the condition does not mention is unconstrained, which is a different
- * thing from one listed with [[SegmentPredicate.orUnset]]
- */
-export type SegmentRuleCondition = SegmentPredicate | AllSegmentPredicate | AnySegmentPredicate;
-
-/**
- * This type represent one rule of a segmented 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 SegmentRule<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: SegmentRuleCondition;
-    /**
-     * The value served when this rule wins
-     */
-    value: T;
-};
-
-/**
- * This type represent the value a segmented 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
- * segmented 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 SegmentedFieldPayload<T = any> = {
-    /**
-     * The rules, in the order they are evaluated in
-     */
-    rules?: SegmentRule<T>[];
-    /**
-     * The value served when no rule matches
-     */
-    fallback?: T;
-};
-
-/**
- * This type represent the visitor's value per segment, as the rule engine reads it. A segment missing
- * from the map, or set to `undefined`, means "not provided" - which is what
- * [[SegmentPredicate.orUnset]] answers
- */
-export type SegmentAssignment = {
-    [segmentMnemonicId: 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 [[SEGMENT_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 segments'
- * 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: SegmentAssignment[];
-    /**
-     * How many assignments reach the fallback, of [[combinations]]
-     */
-    fallbackCount: number;
-    /**
-     * The segments declared by the field but constrained by no rule, so they change nothing about what
-     * it serves
-     */
-    unusedSegments: string[];
-    /**
-     * What [[OTHER_KEY]] stood for, per segment: the real unmentioned keys, capped at 10, with their
-     * total. Only the segments that needed the stand-in appear
-     */
-    otherKeys: { [segment: string]: { keys: string[]; total: number } };
-    /**
-     * Set when the rules and their segments 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 SegmentRuleDraft = {
-    /**
-     * 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?: SegmentRuleCondition;
-};
-
-/**
- * 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 segment 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 AnalyseSegmentRulesRequest = {
-    /**
-     * The mnemonic ids of the segments the field varies by, at most 20. The analysis is bounded by
-     * these, as the field's rules are
-     */
-    segments: 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: SegmentRuleDraft[];
-};
-
-/**
- * This type represent the response of an analyse rules API request
- */
-export type AnalyseSegmentRulesResponse = CoverageReport;