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

package/dist/api/Content.d.ts

@@ -5,6 +5,7 @@ import { ContentDefinitionId, ContentDefinitionResponse } from "./ContentDefinit
 import { SchemaTypeIds } from "./ContentDefinitionSchema";
 import { ContentRepositoryId, ContentRepositoryResponse } from "./ContentRepository";
 import { ContentTranslation, ContentTranslationStatus } from "./ContentTranslation";
+import { CoverageReport } from "./Segment";
 /**
  * This type represent the content unique id type
  */
@@ -824,3 +825,36 @@ export type ToggleContentTranslationsRequest = {
     localizationSettings: LocalizationSettings;
 };
 export type ToggleContentTranslationsResponse = ContentResponse;
+/**
+ * This type represent the data needed to make an analyse segmented rules API request
+ */
+export type AnalyseSegmentedRulesRequest = {
+    /**
+     * Id of the content whose segmented fields have to be analysed
+     */
+    contentId: ContentId;
+};
+/**
+ * This type represent the coverage of one segmented field of a content
+ */
+export type SegmentedFieldCoverage = 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 segmented rules API request: one report per
+ * segmented field of the content, empty when it has none
+ */
+export type AnalyseSegmentedRulesResponse = {
+    /**
+     * One entry per segmented field found in the content payload
+     */
+    fields: SegmentedFieldCoverage[];
+};

package/dist/api/ContentDefinition.d.ts

@@ -266,6 +266,15 @@ 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[];
 };
 /**
  * This type represent the model for the schema fragment errors
@@ -397,5 +406,6 @@ export declare enum SchemaFieldViolationCodes {
     segmentTypeNotAllowed = "segmentTypeNotAllowed",
     segmentNameNotFound = "segmentNameNotFound",
     segmentArchived = "segmentArchived",
+    segmentNotDeclaredByDefinition = "segmentNotDeclaredByDefinition",
     duplicateSegmentName = "duplicateSegmentName"
 }

package/dist/api/ContentDefinition.js

@@ -48,5 +48,6 @@ var SchemaFieldViolationCodes;
     SchemaFieldViolationCodes["segmentTypeNotAllowed"] = "segmentTypeNotAllowed";
     SchemaFieldViolationCodes["segmentNameNotFound"] = "segmentNameNotFound";
     SchemaFieldViolationCodes["segmentArchived"] = "segmentArchived";
+    SchemaFieldViolationCodes["segmentNotDeclaredByDefinition"] = "segmentNotDeclaredByDefinition";
     SchemaFieldViolationCodes["duplicateSegmentName"] = "duplicateSegmentName";
 })(SchemaFieldViolationCodes || (exports.SchemaFieldViolationCodes = SchemaFieldViolationCodes = {}));

package/dist/api/ContentDefinitionSchema.d.ts

@@ -48,6 +48,14 @@ 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[];
 };
 /**
  * This type represent the model of the attribute fragments in a content definition schema
@@ -318,8 +326,13 @@ export type SegmentVariantType = {
  */
 export type SegmentedFieldConstraints = {
     /**
-     * The mnemonic ids of the segments this field varies by. Declaration order carries no meaning: a
-     * rule wins by being first in the content, not by which segment it constrains
+     * 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[];
     /**

package/dist/api/Segment.d.ts

@@ -310,3 +310,134 @@ export type SegmentedFieldPayload<T = any> = {
      */
     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 declare 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;

package/dist/api/Segment.js

@@ -1,9 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEGMENT_NAME_PATTERN = void 0;
+exports.OTHER_KEY = exports.SEGMENT_NAME_PATTERN = void 0;
 /**
  * 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
  */
 exports.SEGMENT_NAME_PATTERN = /^[a-z0-9_-]+$/;
+/**
+ * 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
+ */
+exports.OTHER_KEY = '<any other key>';

package/lib/api/Content.ts

@@ -14,6 +14,7 @@ import {
   ContentTranslation,
   ContentTranslationStatus,
 } from "./ContentTranslation";
+import { CoverageReport } from "./Segment";
 
 /**
  * This type represent the content unique id type
@@ -900,3 +901,39 @@ export type ToggleContentTranslationsRequest = {
 };
 
 export type ToggleContentTranslationsResponse = ContentResponse;
+
+/**
+ * This type represent the data needed to make an analyse segmented rules API request
+ */
+export type AnalyseSegmentedRulesRequest = {
+  /**
+   * Id of the content whose segmented fields have to be analysed
+   */
+  contentId: ContentId;
+};
+
+/**
+ * This type represent the coverage of one segmented field of a content
+ */
+export type SegmentedFieldCoverage = 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 segmented rules API request: one report per
+ * segmented field of the content, empty when it has none
+ */
+export type AnalyseSegmentedRulesResponse = {
+  /**
+   * One entry per segmented field found in the content payload
+   */
+  fields: SegmentedFieldCoverage[];
+};

package/lib/api/ContentDefinition.ts

@@ -287,6 +287,15 @@ 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[];
 };
 
 /**
@@ -425,5 +434,6 @@ export enum SchemaFieldViolationCodes {
     segmentTypeNotAllowed = 'segmentTypeNotAllowed',
     segmentNameNotFound = 'segmentNameNotFound',
     segmentArchived = 'segmentArchived',
+    segmentNotDeclaredByDefinition = 'segmentNotDeclaredByDefinition',
     duplicateSegmentName = 'duplicateSegmentName'
 }

package/lib/api/ContentDefinitionSchema.ts

@@ -51,6 +51,14 @@ 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[];
 };
 
 /**
@@ -341,8 +349,13 @@ export type SegmentVariantType =
  */
 export type SegmentedFieldConstraints = {
     /**
-     * The mnemonic ids of the segments this field varies by. Declaration order carries no meaning: a
-     * rule wins by being first in the content, not by which segment it constrains
+     * 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[];
     /**

package/lib/api/Segment.ts

@@ -334,3 +334,133 @@ export type SegmentedFieldPayload<T = any> = {
      */
     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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.0.0-alpha.2",
+  "version": "11.0.0-alpha.4",
   "description": "ContentChef types",
   "author": "PierpaoloIannone <piannone@byte-code.com>",
   "homepage": "https://github.com/ContentChef/contentchef-management-js-client#readme",
@@ -34,5 +34,5 @@
   "devDependencies": {
     "typescript": "^5.9.3"
   },
-  "gitHead": "58fd14f63fafe3be82bc829bb3a835a2e4f94c30"
+  "gitHead": "e6dc1e7bcc12adafcb1d1428f27bbd3b9e3c2bc5"
 }