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

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
@@ -769,7 +775,18 @@ export declare enum ContentFieldViolationCodes {
     textFieldPatternNotMatched = "textField.patternNotMatched",
     textFieldValueMissingInListOfValue = "textField.valueMissingInListOfValue",
     textFieldValueIsNotAString = "textField.valueIsNotAString",
-    textFieldBlankValueNotAllowed = "textField.blankValueNotAllowed"
+    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"
 }
 /**
  * Request type for getContentStatus

package/dist/api/Content.js

@@ -86,6 +86,17 @@ var ContentFieldViolationCodes;
     ContentFieldViolationCodes["textFieldValueMissingInListOfValue"] = "textField.valueMissingInListOfValue";
     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
@@ -366,6 +371,7 @@ export declare enum SchemaFieldViolationCodes {
     invalidNumberValueInList = "invalidNumberValueInList",
     invalidArrayValue = "invalidArrayValue",
     invalidEmptyArray = "invalidEmptyArray",
+    invalidEmptyObject = "invalidEmptyObject",
     invalidListOfValuesValue = "invalidListOfValuesValue",
     fragmentNameNotFound = "fragmentNameNotFound",
     fragmentNameAlreadyInUse = "fragmentNameAlreadyInUse",
@@ -387,5 +393,9 @@ export declare enum SchemaFieldViolationCodes {
     extensionNotSupportedForType = "extensionNotSupportedForType",
     translatableNotAllowed = "translatableNotAllowed",
     invalidEnumValue = "invalidEnumValue",
-    compactCannotBeNested = "compactCannotBeNested"
+    compactCannotBeNested = "compactCannotBeNested",
+    segmentTypeNotAllowed = "segmentTypeNotAllowed",
+    segmentNameNotFound = "segmentNameNotFound",
+    segmentArchived = "segmentArchived",
+    duplicateSegmentName = "duplicateSegmentName"
 }

package/dist/api/ContentDefinition.js

@@ -22,6 +22,7 @@ var SchemaFieldViolationCodes;
     SchemaFieldViolationCodes["invalidNumberValueInList"] = "invalidNumberValueInList";
     SchemaFieldViolationCodes["invalidArrayValue"] = "invalidArrayValue";
     SchemaFieldViolationCodes["invalidEmptyArray"] = "invalidEmptyArray";
+    SchemaFieldViolationCodes["invalidEmptyObject"] = "invalidEmptyObject";
     SchemaFieldViolationCodes["invalidListOfValuesValue"] = "invalidListOfValuesValue";
     SchemaFieldViolationCodes["fragmentNameNotFound"] = "fragmentNameNotFound";
     SchemaFieldViolationCodes["fragmentNameAlreadyInUse"] = "fragmentNameAlreadyInUse";
@@ -44,4 +45,8 @@ var SchemaFieldViolationCodes;
     SchemaFieldViolationCodes["translatableNotAllowed"] = "translatableNotAllowed";
     SchemaFieldViolationCodes["invalidEnumValue"] = "invalidEnumValue";
     SchemaFieldViolationCodes["compactCannotBeNested"] = "compactCannotBeNested";
+    SchemaFieldViolationCodes["segmentTypeNotAllowed"] = "segmentTypeNotAllowed";
+    SchemaFieldViolationCodes["segmentNameNotFound"] = "segmentNameNotFound";
+    SchemaFieldViolationCodes["segmentArchived"] = "segmentArchived";
+    SchemaFieldViolationCodes["duplicateSegmentName"] = "duplicateSegmentName";
 })(SchemaFieldViolationCodes || (exports.SchemaFieldViolationCodes = SchemaFieldViolationCodes = {}));

package/dist/api/ContentDefinitionSchema.d.ts

@@ -19,7 +19,8 @@ export declare enum SchemaTypeIds {
     ONE_LINKED_CONTENT_OF = "oneLinkedContentOf",
     ARRAY = "array",
     SLUG = "slug",
-    MEDIA = "media"
+    MEDIA = "media",
+    SEGMENTED = "segmented"
 }
 /**
  * This enum represent al possible long text sub types
@@ -293,6 +294,39 @@ export type OneLinkedContentOfConstraints = {
     lazy?: boolean;
     linkType?: LinkType;
 };
+/**
+ * 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
+ *
+ * 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 = {
+    type: SchemaTypeIds.ONE_FRAGMENT_OF;
+    constraints: OneFragmentOfConstraints;
+} | {
+    type: SchemaTypeIds.ONE_LINKED_CONTENT_OF;
+    constraints: OneLinkedContentOfConstraints;
+};
+/**
+ * This type represent the model of a segmented field constraints
+ *
+ * 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 = {
+    /**
+     * 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
+     */
+    segments: string[];
+    /**
+     * The shape every rule value and the fallback conform to
+     */
+    variantType: SegmentVariantType;
+};
 /**
  * This type represent the model of an array field constraints
  * @template T The type of the item used ad children of the array
@@ -444,6 +478,10 @@ export type OneFragmentOfSchemaType = SchemaType<SchemaTypeIds.ONE_FRAGMENT_OF,
  * A one linked content of field can be indexed and searched when requesting the content
  */
 export type OneLinkedContentOfSchemaType = IndexableSchemaType<SchemaTypeIds.ONE_LINKED_CONTENT_OF, OneLinkedContentOfConstraints>;
+/**
+ * This type represent a segmented field schema type
+ */
+export type SegmentedSchemaType = SchemaType<SchemaTypeIds.SEGMENTED, SegmentedFieldConstraints>;
 /**
  * Slug schema type
  * This type is indexable and translatable by default
@@ -469,7 +507,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;
+export type PlainSchemaTypes = DateSchemaType | FragmentSchemaType | OneFragmentOfSchemaType | SlugSchemaType | SegmentedSchemaType;
 /**
  * This type group all schema types of a content definition
  */

package/dist/api/ContentDefinitionSchema.js

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

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[];
 };
 
 /**
@@ -838,6 +845,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",
 }
 
 /**

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[];
 };
 
 /**
@@ -393,6 +399,7 @@ export enum SchemaFieldViolationCodes {
     invalidNumberValueInList = 'invalidNumberValueInList',
     invalidArrayValue = 'invalidArrayValue',
     invalidEmptyArray = 'invalidEmptyArray',
+    invalidEmptyObject = 'invalidEmptyObject',
     invalidListOfValuesValue = 'invalidListOfValuesValue',
     fragmentNameNotFound = 'fragmentNameNotFound',
     fragmentNameAlreadyInUse = 'fragmentNameAlreadyInUse',
@@ -414,5 +421,9 @@ export enum SchemaFieldViolationCodes {
     extensionNotSupportedForType = 'extensionNotSupportedForType',
     translatableNotAllowed = 'translatableNotAllowed',
     invalidEnumValue = 'invalidEnumValue',
-    compactCannotBeNested = 'compactCannotBeNested'
+    compactCannotBeNested = 'compactCannotBeNested',
+    segmentTypeNotAllowed = 'segmentTypeNotAllowed',
+    segmentNameNotFound = 'segmentNameNotFound',
+    segmentArchived = 'segmentArchived',
+    duplicateSegmentName = 'duplicateSegmentName'
 }

package/lib/api/ContentDefinitionSchema.ts

@@ -21,6 +21,7 @@ export enum SchemaTypeIds {
     ARRAY = 'array',
     SLUG = 'slug',
     MEDIA = 'media',
+    SEGMENTED = 'segmented',
 }
 
 /**
@@ -319,6 +320,37 @@ export type OneLinkedContentOfConstraints = {
     linkType?: LinkType;
 };
 
+/**
+ * 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
+ *
+ * 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 =
+    | { type: SchemaTypeIds.ONE_FRAGMENT_OF; constraints: OneFragmentOfConstraints; }
+    | { type: SchemaTypeIds.ONE_LINKED_CONTENT_OF; constraints: OneLinkedContentOfConstraints; };
+
+/**
+ * This type represent the model of a segmented field constraints
+ *
+ * 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 = {
+    /**
+     * 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
+     */
+    segments: string[];
+    /**
+     * The shape every rule value and the fallback conform to
+     */
+    variantType: SegmentVariantType;
+};
+
 /**
  * This type represent the model of an array field constraints
  * @template T The type of the item used ad children of the array
@@ -483,6 +515,11 @@ 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
+ */
+export type SegmentedSchemaType = SchemaType<SchemaTypeIds.SEGMENTED, SegmentedFieldConstraints>;
+
 /**
  * Slug schema type
  * This type is indexable and translatable by default
@@ -515,7 +552,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;
+export type PlainSchemaTypes = DateSchemaType | FragmentSchemaType | OneFragmentOfSchemaType | SlugSchemaType | SegmentedSchemaType;
 
 /**
  * This type group all schema types of a content definition

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.0",
+  "version": "11.0.0-alpha.2",
   "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": "2e427740786a96ee2e1d8262371799287a33dc88"
+  "gitHead": "58fd14f63fafe3be82bc829bb3a835a2e4f94c30"
 }