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

package/lib/api/ContentDefinitionSchema.ts

@@ -51,14 +51,6 @@ export type ContentDefinitionSchema = {
      * A Fragment is a custom field defined by the user and can be used internally in the definition
      */
     fragments: FragmentsTable;
-    /**
-     * The audiences this definition depends on, chosen by the author. Every one has to exist in the
-     * space and not be archived, and a personalized field may only vary by audiences named here, so this
-     * is what scopes a definition and gives the field editor a short list to offer
-     *
-     * Optional: a definition that declares none simply cannot hold a personalized field
-     */
-    audiences?: string[];
 };
 
 /**
@@ -330,7 +322,7 @@ export type OneLinkedContentOfConstraints = {
 
 /**
  * This type represent what every value of a personalized field holds: one descriptor for the whole field,
- * so the rules and the fallback cannot differ in type
+ * so the variants 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
@@ -342,24 +334,14 @@ export type PersonalizedVariantType =
 /**
  * This type represent the model of a personalized field constraints
  *
- * A personalized field declares only *what varies* and *what shape the values have*. Which conditions
- * exist and what each of them serves is authored per content, as an ordered list of rules plus a
- * fallback - see [[PersonalizedFieldPayload]] - so no combination has to be pre-declared here and two
- * contents of the same definition may carry entirely different rule sets
+ * A personalized field says only *what shape the values have*. Which audiences it serves is authored
+ * per content, as an ordered list of variants plus a fallback - see [[PersonalizedFieldPayload]] - so
+ * nothing has to be pre-declared here and two contents of the same definition may target entirely
+ * different audiences
  */
 export type PersonalizedFieldConstraints = {
     /**
-     * The mnemonic ids of the audiences this field varies by, which must be among the ones the
-     * definition declares in [[ContentDefinitionSchema.audiences]]. Only the declaration is checked
-     * against the space, so an audience that does not exist is one error on the definition rather than
-     * one on every field that reached for it
-     *
-     * Declaration order carries no meaning: a rule wins by being first in the content, not by which
-     * audience it constrains
-     */
-    audiences: string[];
-    /**
-     * The shape every rule value and the fallback conform to
+     * The shape every variant value and the fallback conform to
      */
     variantType: PersonalizedVariantType;
 };

package/lib/api/Dimension.ts

@@ -0,0 +1,274 @@
+import { AuthorResponse } from './Author';
+import { PagedListResponse } from './common';
+
+/**
+ * The dimension unique id
+ */
+export type DimensionId = number;
+
+/**
+ * A dimension's mnemonicId and every one of its keys must match this pattern: lowercase, digits,
+ * underscore and hyphen. Stricter than the other authoring mnemonicIds on purpose, because both halves
+ * travel in the delivery `audiences` query param and are compared against strings a client supplies
+ */
+export const DIMENSION_NAME_PATTERN = /^[a-z0-9_-]+$/;
+
+/**
+ * This type represent one key of a dimension, that is one of the values a visitor can have for it
+ */
+export type DimensionKey = {
+    /**
+     * The key, matching [[DIMENSION_NAME_PATTERN]]
+     */
+    key: string;
+    /**
+     * A deprecated key cannot be referenced by new audience rules, while every rule already written
+     * keeps resolving. The flag toggles both ways
+     */
+    deprecated?: boolean;
+};
+
+/**
+ * This type represent the model of a dimension, that is something a visitor can be described by -
+ * `gender`, `loyalty`, `auth_status` - holding the fixed set of keys they can have for it
+ *
+ * Dimensions are what audience rules are written over, and a visitor's values for them are what the
+ * delivery request carries. Audiences reference a dimension by mnemonicId and key, so dimensions are
+ * archived and never deleted, and a key can only be removed or renamed while no audience uses it
+ */
+export type DimensionResponse = {
+    /**
+     * The dimension unique id
+     */
+    id: DimensionId;
+    /**
+     * The dimension name
+     */
+    name: string;
+    /**
+     * The dimension mnemonic id, matching [[DIMENSION_NAME_PATTERN]]
+     */
+    mnemonicId: string;
+    /**
+     * The keys a visitor can hold for this dimension, each carrying its own deprecation state
+     */
+    keys: DimensionKey[];
+    /**
+     * The archived status of the dimension
+     */
+    archived: boolean;
+    /**
+     * The archive date of the dimension
+     */
+    archivedDate: Date | null;
+    /**
+     * The dimension creation date
+     */
+    createdDate: Date;
+    /**
+     * The dimension last modified date
+     */
+    lastModifiedDate: Date;
+    /**
+     * The dimension author, resolved by `list` only
+     */
+    author?: AuthorResponse;
+    /**
+     * The dimension last modified author, resolved by every endpoint but `get`
+     */
+    latestContributor?: AuthorResponse;
+};
+
+/**
+ * This type represent all possible filters used to retrieve a list of dimension
+ */
+export type ListDimensionsFilters = {
+    /**
+     * This filter is used to retrieve archived or not archived dimensions. Defaults to not archived
+     */
+    archived?: boolean;
+    /**
+     * This filter is used to search dimensions whose name or mnemonic id contain the value inserted,
+     * case insensitively. At most 100 characters
+     */
+    name?: string;
+};
+
+/**
+ * This type represent the data needed to make a list dimensions API request
+ */
+export type ListDimensionsRequest = {
+    /**
+     * The number of dimensions to skip (this value is used for pagination)
+     */
+    skip?: number;
+    /**
+     * The number of dimensions to take (this value is used for pagination), at most 100
+     */
+    take?: number;
+    /**
+     * The data used to filter the list of dimensions
+     */
+    filters?: ListDimensionsFilters;
+};
+
+/**
+ * This type represent the item of a list dimensions API request
+ */
+export type ListDimensionsItem = DimensionResponse;
+
+/**
+ * This type represent the response of a list dimensions API request
+ */
+export type ListDimensionsResponse = PagedListResponse<ListDimensionsItem>;
+
+/**
+ * This type represent the usage of one key of a dimension. A key with no entry is named by no audience
+ * rule, and is therefore the only kind of key that can be removed or renamed
+ */
+export type DimensionKeyUsage = {
+    /**
+     * The key, or null for the rules that constrain the dimension without naming any key - that is the
+     * ones that only fire when the dimension is unknown
+     */
+    key: string | null;
+    /**
+     * How many audiences reference this key
+     */
+    audiences: number;
+};
+
+/**
+ * This type represent an audience whose rule names a dimension
+ */
+export type AudienceUsingDimension = {
+    /**
+     * The audience unique id
+     */
+    id: number;
+    /**
+     * The audience mnemonic id
+     */
+    mnemonicId: string;
+    /**
+     * The audience name
+     */
+    name: string;
+};
+
+/**
+ * This type represent the data needed to make a get dimension API request
+ */
+export type GetDimensionRequest = {
+    /**
+     * The unique dimension id to retrieve
+     */
+    id: DimensionId;
+};
+
+/**
+ * This type represent the response of a get dimension API request: the dimension, plus the two things
+ * the editor cannot decide without, which keys are in use and which audiences are written against it
+ */
+export type GetDimensionResponse = DimensionResponse & {
+    /**
+     * One entry per key at least one audience rule names. A key absent from this list is unused
+     */
+    keyUsage: DimensionKeyUsage[];
+    /**
+     * The audiences whose rule names this dimension
+     */
+    audiences: AudienceUsingDimension[];
+};
+
+/**
+ * This type represent the data needed to make a create dimension API request
+ */
+export type CreateDimensionRequest = {
+    /**
+     * The dimension name
+     */
+    name: string;
+    /**
+     * The dimension mnemonic id, matching [[DIMENSION_NAME_PATTERN]]
+     */
+    mnemonicId: string;
+    /**
+     * The keys a visitor can hold for this dimension, at least one, each key unique
+     */
+    keys: DimensionKey[];
+};
+
+/**
+ * This type represent the response of a create dimension API request
+ */
+export type CreateDimensionResponse = DimensionResponse;
+
+/**
+ * This type represent the data needed to make an update dimension 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 an audience rule
+ * still names it. `mnemonicId` cannot be changed
+ */
+export type UpdateDimensionRequest = {
+    /**
+     * The dimension unique id
+     */
+    id: DimensionId;
+    /**
+     * The dimension name to update
+     */
+    name: string;
+    /**
+     * The dimension mnemonic id, which must be the stored one
+     */
+    mnemonicId: string;
+    /**
+     * The whole key list, replacing what is stored
+     */
+    keys: DimensionKey[];
+};
+
+/**
+ * This type represent the response of an update dimension API request
+ */
+export type UpdateDimensionResponse = DimensionResponse;
+
+/**
+ * This type represent the data needed to make a toggle archived dimension API request
+ */
+export type ToggleArchivedDimensionRequest = {
+    /**
+     * The dimension unique id
+     */
+    id: DimensionId;
+    /**
+     * This value represent the archive status to set in the specified dimension
+     */
+    archived: boolean;
+};
+
+/**
+ * This type represent the response of a toggle archived dimension API request
+ */
+export type ToggleArchivedDimensionResponse = DimensionResponse;
+
+/**
+ * This type represent a visitor's value per dimension, as the rule engine reads it. A dimension missing
+ * from the map, or set to `undefined`, means "not provided" - which is what
+ * [[DimensionPredicate.orUnset]] answers
+ */
+export type DimensionAssignment = {
+    [dimensionMnemonicId: string]: string | undefined;
+};
+
+/**
+ * The stand-in a coverage report uses for "a key none of the analysed rules mention"
+ *
+ * Not a real key - it cannot be one, since keys match [[DIMENSION_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>';

package/lib/api/index.ts

@@ -8,6 +8,7 @@ export * from './ContentDefinitionSchema';
 export * from './ContentExportImport';
 export * from './ContentRepository';
 export * from './ContentTag';
+export * from './Dimension';
 export * from './Invites';
 export * from './MediaGallery';
 export * from './PublishedContent';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentchef/contentchef-types",
-  "version": "11.0.0-alpha.5",
+  "version": "11.0.0-alpha.7",
   "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": "9aec2cdbb2d04b788dec73666e71eb36f867944a"
+  "gitHead": "85695d5bd81fb801da3ab37fba91c841ab8d47ae"
 }