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

package/dist/api/Content.d.ts

@@ -367,6 +367,12 @@ export type ListContentsFilters = {
      * Filter list by ContentTranslation status
      */
     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
+     */
+    segments?: string[];
 };
 /**
  * This type represent the data needed to make a list content API request
@@ -771,7 +777,16 @@ export declare enum ContentFieldViolationCodes {
     textFieldValueIsNotAString = "textField.valueIsNotAString",
     textFieldBlankValueNotAllowed = "textField.blankValueNotAllowed",
     segmentedFieldValueIsNotSegmented = "segmentedField.valueIsNotSegmented",
-    segmentedFieldSegmentNotDeclared = "segmentedField.segmentNotDeclared"
+    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"
 }
 /**
  * Request type for getContentStatus

package/dist/api/Content.js

@@ -87,7 +87,16 @@ var ContentFieldViolationCodes;
     ContentFieldViolationCodes["textFieldValueIsNotAString"] = "textField.valueIsNotAString";
     ContentFieldViolationCodes["textFieldBlankValueNotAllowed"] = "textField.blankValueNotAllowed";
     ContentFieldViolationCodes["segmentedFieldValueIsNotSegmented"] = "segmentedField.valueIsNotSegmented";
+    ContentFieldViolationCodes["segmentedFieldRulesIsNotAnArray"] = "segmentedField.rulesIsNotAnArray";
+    ContentFieldViolationCodes["segmentedFieldRuleIsNotAnObject"] = "segmentedField.ruleIsNotAnObject";
+    ContentFieldViolationCodes["segmentedFieldRuleConditionMissing"] = "segmentedField.ruleConditionMissing";
+    ContentFieldViolationCodes["segmentedFieldDuplicateRuleId"] = "segmentedField.duplicateRuleId";
     ContentFieldViolationCodes["segmentedFieldSegmentNotDeclared"] = "segmentedField.segmentNotDeclared";
+    ContentFieldViolationCodes["segmentedFieldFallbackRequired"] = "segmentedField.fallbackRequired";
+    ContentFieldViolationCodes["segmentedFieldSegmentNotFound"] = "segmentedField.segmentNotFound";
+    ContentFieldViolationCodes["segmentedFieldSegmentArchived"] = "segmentedField.segmentArchived";
+    ContentFieldViolationCodes["segmentedFieldSegmentKeyNotFound"] = "segmentedField.segmentKeyNotFound";
+    ContentFieldViolationCodes["segmentedFieldSegmentKeyDeprecated"] = "segmentedField.segmentKeyDeprecated";
 })(ContentFieldViolationCodes || (exports.ContentFieldViolationCodes = ContentFieldViolationCodes = {}));
 var LocalizationSettings;
 (function (LocalizationSettings) {

package/dist/api/ContentDefinition.d.ts

@@ -175,6 +175,11 @@ 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[];
 };
 /**
  * This type represent the response of a create content definition API request
@@ -261,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
@@ -390,5 +404,8 @@ export declare enum SchemaFieldViolationCodes {
     invalidEnumValue = "invalidEnumValue",
     compactCannotBeNested = "compactCannotBeNested",
     segmentTypeNotAllowed = "segmentTypeNotAllowed",
-    segmentNameNotFound = "segmentNameNotFound"
+    segmentNameNotFound = "segmentNameNotFound",
+    segmentArchived = "segmentArchived",
+    segmentNotDeclaredByDefinition = "segmentNotDeclaredByDefinition",
+    duplicateSegmentName = "duplicateSegmentName"
 }

package/dist/api/ContentDefinition.js

@@ -47,4 +47,7 @@ var SchemaFieldViolationCodes;
     SchemaFieldViolationCodes["compactCannotBeNested"] = "compactCannotBeNested";
     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
@@ -295,66 +303,42 @@ export type OneLinkedContentOfConstraints = {
     linkType?: LinkType;
 };
 /**
- * This type represent one segment of a segmented field: the same `{ type, constraints }` pair a
- * schema field carries, minus the name, because the map key in `SegmentsTable` is the name
+ * 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
  *
- * `oneLinkedContentOf` is the only reference form admitted, `linked-content` is its single
- * definition special case and carries the identical payload value
+ * 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 SegmentDescriptor = {
-    type: SchemaTypeIds.FRAGMENT;
-    constraints: FragmentFieldConstraints;
-} | {
+export type SegmentVariantType = {
     type: SchemaTypeIds.ONE_FRAGMENT_OF;
     constraints: OneFragmentOfConstraints;
 } | {
     type: SchemaTypeIds.ONE_LINKED_CONTENT_OF;
     constraints: OneLinkedContentOfConstraints;
 };
-/**
- * This type represent the model to define a segment of a segmented field
- */
-export type SegmentDefinition = SegmentDescriptor & {
-    /**
-     * The friendly labels of the segment
-     */
-    labels?: I18NDictionary;
-};
-/**
- * This type represent the model of the attribute segments of a segmented field, keyed by segment
- * name, like `FragmentsTable`
- * Names must match `^[a-z0-9_-]+$` and are unordered
- */
-export type SegmentsTable = {
-    /**
-     * The name is the unique id of the segment and its value is the model representing the segment
-     */
-    [name: string]: SegmentDefinition;
-};
-/**
- * This enum constrains every segment of a field to one family
- * When omitted, segments of both families are allowed in the same field
- */
-export declare enum SegmentsType {
-    FRAGMENTS = "fragments",
-    REFERENCES = "references"
-}
 /**
  * This type represent the model of a segmented 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
  */
 export type SegmentedFieldConstraints = {
     /**
-     * Set this value to define the segments the field is made of
-     */
-    segments: SegmentsTable;
-    /**
-     * Set this value to define the segment served when the request matches none of this field's segments
+     * 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
      */
-    defaultSegment?: string;
+    segments: string[];
     /**
-     * Set this value to constrain every segment of the field to one family
+     * The shape every rule value and the fallback conform to
      */
-    segmentsType?: SegmentsType;
+    variantType: SegmentVariantType;
 };
 /**
  * This type represent the model of an array field constraints

package/dist/api/ContentDefinitionSchema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SegmentsType = exports.LinkType = exports.LongTextSubTypes = exports.SchemaTypeIds = void 0;
+exports.LinkType = exports.LongTextSubTypes = exports.SchemaTypeIds = void 0;
 /**
  * This enum represent al possible schema field type ids
  */
@@ -40,12 +40,3 @@ var LinkType;
     LinkType[LinkType["LAZY"] = 1] = "LAZY";
     LinkType[LinkType["COMPACT"] = 2] = "COMPACT";
 })(LinkType || (exports.LinkType = LinkType = {}));
-/**
- * This enum constrains every segment of a field to one family
- * When omitted, segments of both families are allowed in the same field
- */
-var SegmentsType;
-(function (SegmentsType) {
-    SegmentsType["FRAGMENTS"] = "fragments";
-    SegmentsType["REFERENCES"] = "references";
-})(SegmentsType || (exports.SegmentsType = SegmentsType = {}));

package/dist/api/Segment.d.ts

@@ -0,0 +1,312 @@
+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 declare const SEGMENT_NAME_PATTERN: RegExp;
+/**
+ * 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;
+};

package/dist/api/Segment.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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_-]+$/;

package/dist/api/index.d.ts

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

package/dist/api/index.js

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

package/lib/api/Content.ts

@@ -401,6 +401,13 @@ export type ListContentsFilters = {
    * Filter list by ContentTranslation status
    */
   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
+   */
+  segments?: string[];
 };
 
 /**
@@ -839,7 +846,16 @@ export enum ContentFieldViolationCodes {
   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",
 }
 
 /**

package/lib/api/ContentDefinition.ts

@@ -189,6 +189,12 @@ 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[];
 };
 
 /**
@@ -281,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[];
 };
 
 /**
@@ -417,5 +432,8 @@ export enum SchemaFieldViolationCodes {
     invalidEnumValue = 'invalidEnumValue',
     compactCannotBeNested = 'compactCannotBeNested',
     segmentTypeNotAllowed = 'segmentTypeNotAllowed',
-    segmentNameNotFound = 'segmentNameNotFound'
+    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[];
 };
 
 /**
@@ -321,64 +329,39 @@ export type OneLinkedContentOfConstraints = {
 };
 
 /**
- * This type represent one segment of a segmented field: the same `{ type, constraints }` pair a
- * schema field carries, minus the name, because the map key in `SegmentsTable` is the name
+ * 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
  *
- * `oneLinkedContentOf` is the only reference form admitted, `linked-content` is its single
- * definition special case and carries the identical payload value
+ * 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 SegmentDescriptor =
-    | { type: SchemaTypeIds.FRAGMENT; constraints: FragmentFieldConstraints; }
+export type SegmentVariantType =
     | { type: SchemaTypeIds.ONE_FRAGMENT_OF; constraints: OneFragmentOfConstraints; }
     | { type: SchemaTypeIds.ONE_LINKED_CONTENT_OF; constraints: OneLinkedContentOfConstraints; };
 
-/**
- * This type represent the model to define a segment of a segmented field
- */
-export type SegmentDefinition = SegmentDescriptor & {
-    /**
-     * The friendly labels of the segment
-     */
-    labels?: I18NDictionary;
-};
-
-/**
- * This type represent the model of the attribute segments of a segmented field, keyed by segment
- * name, like `FragmentsTable`
- * Names must match `^[a-z0-9_-]+$` and are unordered
- */
-export type SegmentsTable = {
-    /**
-     * The name is the unique id of the segment and its value is the model representing the segment
-     */
-    [name: string]: SegmentDefinition;
-};
-
-/**
- * This enum constrains every segment of a field to one family
- * When omitted, segments of both families are allowed in the same field
- */
-export enum SegmentsType {
-    FRAGMENTS = 'fragments',
-    REFERENCES = 'references'
-}
-
 /**
  * This type represent the model of a segmented 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
  */
 export type SegmentedFieldConstraints = {
     /**
-     * Set this value to define the segments the field is made of
-     */
-    segments: SegmentsTable;
-    /**
-     * Set this value to define the segment served when the request matches none of this field's segments
+     * 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
      */
-    defaultSegment?: string;
+    segments: string[];
     /**
-     * Set this value to constrain every segment of the field to one family
+     * The shape every rule value and the fallback conform to
      */
-    segmentsType?: SegmentsType;
+    variantType: SegmentVariantType;
 };
 
 /**

package/lib/api/Segment.ts

@@ -0,0 +1,336 @@
+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;
+};

package/lib/api/index.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.0.0-alpha.1",
+  "version": "11.0.0-alpha.3",
   "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": "b618c00d0b1642ac9a75685fa08e214b83e22fc8"
+  "gitHead": "778b33af62f27ed0f992fc1d50025f2cf8c90836"
 }