@unito/integration-api 8.0.7 → 8.0.9

package/dist/src/compatibilities.d.ts

@@ -570,7 +570,7 @@ export declare const fieldTypeCompatibilityMatrix: {
                 readonly required: true;
             };
         };
-        readonly richText: {};
+        readonly richText: null;
         readonly html: {};
         readonly markdown: {};
         readonly string: {};

package/dist/src/compatibilities.js

@@ -403,7 +403,7 @@ export const fieldTypeCompatibilityMatrix = {
         [Api.FieldValueTypes.NUMBER]: {},
         [Api.FieldValueTypes.OBJECT]: null,
         [Api.FieldValueTypes.REFERENCE]: stringLikeToReferenceConfiguration,
-        [Api.FieldValueTypes.RICH_TEXT]: {},
+        [Api.FieldValueTypes.RICH_TEXT]: null,
         [Api.FieldValueTypes.RICH_TEXT_HTML]: {},
         [Api.FieldValueTypes.RICH_TEXT_MARKDOWN]: {},
         [Api.FieldValueTypes.STRING]: {},

package/dist/src/fieldHelpers.d.ts

@@ -0,0 +1,57 @@
+import { FieldSchema, FieldValues, Semantic } from './types.js';
+declare const ValidFieldValueEntryBrand: unique symbol;
+/**
+ * A single field value that has been validated against its FieldSchema.
+ */
+export type ValidFieldValueEntry<T> = T & {
+    [ValidFieldValueEntryBrand]: 'ValidFieldValueEntry';
+};
+declare const ValidFieldValueBrand: unique symbol;
+/**
+ * A field value (single, array or null) that has been validated against its FieldSchema.
+ */
+export type ValidFieldValue<T> = (ValidFieldValueEntry<T> | ValidFieldValueEntry<T>[] | null) & {
+    [ValidFieldValueBrand]: 'ValidFieldValue';
+};
+/**
+ * Escapes characters that would otherwise break dotted field name path parsing.
+ */
+export declare function sanitizeFieldName(fieldName: string): string;
+/**
+ * Reverses sanitizeFieldName.
+ */
+export declare function unsanitizeFieldName(fieldName: string): string;
+/**
+ * Returns the validated value of a field, looking it up by name and falling back to its `semantic:` key.
+ *
+ * @throws Error if the value is invalid.
+ */
+export declare function getUnsafeValue<T = unknown>(field: FieldSchema, values: FieldValues): ValidFieldValue<T>;
+/**
+ * Same as getUnsafeValue, but returns undefined instead of throwing on invalid values.
+ */
+export declare function getSafeValue<T = unknown>(field: FieldSchema, values: FieldValues): ReturnType<typeof getUnsafeValue<T>> | undefined;
+/**
+ * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ */
+export declare function findValueByName<T = unknown>(fields: FieldSchema[], values: FieldValues, fieldName: string): ReturnType<typeof getSafeValue<T>>;
+interface InheritedFieldProperties {
+    isArray?: boolean | undefined;
+    canSetOnCreate?: boolean | undefined;
+    canSetOnUpdate?: boolean | undefined;
+    nullable?: boolean | undefined;
+}
+/**
+ * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ */
+export declare function findFieldByName(fields: FieldSchema[], fieldName: string, inheritedProperties?: InheritedFieldProperties): FieldSchema | undefined;
+/**
+ * Returns a field schema by its semantic.
+ *
+ * @throws Error if the found field does not respect the type constraints of its semantic.
+ */
+export declare function findFieldBySemantic<T extends Semantic>(fields: FieldSchema[], semantic: T): Extract<FieldSchema, {
+    semantic: T;
+}> | undefined;
+export {};

package/dist/src/fieldHelpers.js

@@ -0,0 +1,308 @@
+import { FieldValueTypes, Semantics } from './types.js';
+import { isItemSummary, isObject, isRelationPointer } from './guards.js';
+/**
+ * Escapes characters that would otherwise break dotted field name path parsing.
+ */
+export function sanitizeFieldName(fieldName) {
+    return fieldName.replaceAll('.', '__UNITO__DOT__').replaceAll('$', '__UNITO__DOLLAR__');
+}
+/**
+ * Reverses sanitizeFieldName.
+ */
+export function unsanitizeFieldName(fieldName) {
+    return fieldName.replaceAll('__UNITO__DOT__', '.').replaceAll('__UNITO__DOLLAR__', '$');
+}
+/**
+ * Validates that a field schema received over the wire respects the type constraints of its semantic.
+ */
+function validateSemanticFieldSchema(field) {
+    if (field.semantic === Semantics.CREATED_AT || field.semantic === Semantics.UPDATED_AT) {
+        if (field.type !== FieldValueTypes.DATETIME) {
+            throw new Error(`Expected ${field.semantic} field to be a DATETIME, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected ${field.semantic} field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.DISPLAY_NAME) {
+        if (field.type !== FieldValueTypes.STRING && field.type !== FieldValueTypes.EMAIL) {
+            throw new Error(`Expected displayName field to be a STRING or EMAIL, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected displayName field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.PROVIDER_URL) {
+        if (field.type !== FieldValueTypes.URL) {
+            throw new Error(`Expected providerUrl field to be a URL, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected providerUrl field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.DESCRIPTION) {
+        if (field.type !== FieldValueTypes.STRING &&
+            field.type !== FieldValueTypes.RICH_TEXT_HTML &&
+            field.type !== FieldValueTypes.RICH_TEXT_MARKDOWN &&
+            field.type !== FieldValueTypes.RICH_TEXT) {
+            throw new Error(`Expected description field to be a STRING, RICH_TEXT_HTML, RICH_TEXT_MARKDOWN or RICH_TEXT, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected description field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.IS_PUBLIC && field.type !== FieldValueTypes.BOOLEAN) {
+        throw new Error(`Expected isPublic field to be a BOOLEAN, got ${field.type}`);
+    }
+    if ((field.semantic === Semantics.USER || field.semantic === Semantics.PARENT) &&
+        field.type !== FieldValueTypes.REFERENCE) {
+        throw new Error(`Expected ${field.semantic} field to be a REFERENCE, got ${field.type}`);
+    }
+}
+/**
+ * Validates a value against a specific type.
+ */
+function validateFieldValueType(field, value) {
+    if (field.type === FieldValueTypes.STRING && typeof value !== 'string') {
+        throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.EMAIL) {
+        if (typeof value !== 'string') {
+            throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+        }
+        // Inspired by https://github.com/manishsaraan/email-validator/blob/master/index.js
+        const emailRegex = /^[-!#$%&'*+/0-9=?A-Z^_a-z`{|}~](\.?[-!#$%&'*+/0-9=?A-Z^_a-z`{|}~])*@[a-zA-Z0-9](-*\.?[a-zA-Z0-9])*\.[a-zA-Z](-?[a-zA-Z0-9])+$/;
+        if (!emailRegex.test(value)) {
+            throw new Error(`Expected ${field.name} to be a valid email address`);
+        }
+    }
+    if (field.type === FieldValueTypes.URL) {
+        if (typeof value !== 'string') {
+            throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+        }
+        try {
+            new URL(value.startsWith('http') ? value : `http://${value}`);
+        }
+        catch {
+            throw new Error(`Expected ${field.name} to be a valid URL`);
+        }
+    }
+    if (field.type === FieldValueTypes.NUMBER && typeof value !== 'number') {
+        throw new Error(`Expected ${field.name} to be a number, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.INTEGER) {
+        if (typeof value !== 'number') {
+            throw new Error(`Expected ${field.name} to be a number, got ${typeof value}`);
+        }
+        if (!Number.isInteger(value)) {
+            throw new Error(`Expected ${field.name} to be an integer, got ${value}`);
+        }
+    }
+    if (field.type === FieldValueTypes.BOOLEAN && typeof value !== 'boolean') {
+        throw new Error(`Expected ${field.name} to be a boolean, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.OBJECT && !isObject(value)) {
+        throw new Error(`Expected ${field.name} to be an object, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.REFERENCE && !isItemSummary(value)) {
+        throw new Error(`Expected ${field.name} to be an ItemSummary, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.DATETIME && (typeof value !== 'string' || isNaN(Date.parse(value)))) {
+        throw new Error(`Expected ${field.name} to be a valid ISO datetime string, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.DATE && (typeof value !== 'string' || isNaN(Date.parse(value)))) {
+        throw new Error(`Expected ${field.name} to be a valid ISO date string, got ${typeof value}`);
+    }
+}
+/**
+ * Validates a field value against its schema.
+ */
+function validateFieldValue(field, value) {
+    if (value === undefined) {
+        throw new Error(`Expected ${field.name} to be defined, got undefined`);
+    }
+    if (field.nullable === false && value === null) {
+        throw new Error(`Expected ${field.name} to be defined, got null`);
+    }
+    if (value === null) {
+        return;
+    }
+    if (field.isArray && !Array.isArray(value)) {
+        throw new Error(`Expected ${field.name} to be an array, got ${typeof value}`);
+    }
+    if (!field.isArray && Array.isArray(value)) {
+        throw new Error(`Expected ${field.name} to be a single value, got an array`);
+    }
+    if (Array.isArray(value)) {
+        for (const subvalue of value) {
+            validateFieldValueType(field, subvalue);
+        }
+    }
+    else {
+        validateFieldValueType(field, value);
+    }
+}
+/**
+ * Returns the validated value of a field, looking it up by name and falling back to its `semantic:` key.
+ *
+ * @throws Error if the value is invalid.
+ */
+export function getUnsafeValue(field, values) {
+    let value = values[field.name];
+    if (value === undefined) {
+        if (field.semantic && `semantic:${field.semantic}` in values) {
+            value = values[`semantic:${field.semantic}`];
+        }
+    }
+    validateFieldValue(field, value);
+    return value;
+}
+/**
+ * Same as getUnsafeValue, but returns undefined instead of throwing on invalid values.
+ */
+export function getSafeValue(field, values) {
+    try {
+        return getUnsafeValue(field, values);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ */
+export function findValueByName(fields, values, fieldName) {
+    const [baseFieldName, ...subFieldNames] = fieldName.split('.');
+    if (baseFieldName === undefined) {
+        return undefined;
+    }
+    const baseField = findFieldByName(fields, baseFieldName);
+    if (!baseField) {
+        if (subFieldNames.length === 0) {
+            return undefined;
+        }
+        const literalField = findFieldByName(fields, fieldName);
+        return literalField ? getSafeValue(literalField, values) : undefined;
+    }
+    const baseFieldValue = getSafeValue(baseField, values);
+    if (subFieldNames.length === 0) {
+        return baseFieldValue;
+    }
+    if (baseField.type === FieldValueTypes.OBJECT) {
+        const subFieldName = subFieldNames.join('.');
+        if (isObject(baseFieldValue)) {
+            return findValueByName(baseField.fields, baseFieldValue, subFieldName);
+        }
+        if (Array.isArray(baseFieldValue)) {
+            return baseFieldValue
+                .map(value => (isObject(value) ? findValueByName(baseField.fields, value, subFieldName) : undefined))
+                .filter(value => value !== undefined);
+        }
+    }
+    if (baseField.type === FieldValueTypes.REFERENCE) {
+        if (isRelationPointer(baseField.reference)) {
+            throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+        }
+        if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
+            subFieldNames.shift();
+        }
+        const subFieldName = subFieldNames.join('.');
+        const referenceFields = baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields;
+        if (isItemSummary(baseFieldValue)) {
+            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName);
+        }
+        if (Array.isArray(baseFieldValue)) {
+            return baseFieldValue
+                .map(value => isItemSummary(value) ? findValueByName(referenceFields, value.fields ?? {}, subFieldName) : undefined)
+                .filter(value => value !== undefined);
+        }
+    }
+    return undefined;
+}
+/**
+ * Subfields inherit some of their parents' properties: a subfield of an array field yields multiple
+ * values, and a subfield of a read-only field cannot be written to.
+ */
+function mergeInheritedProperties(field, inherited) {
+    const merged = { ...field };
+    const isArray = inherited.isArray || field.isArray;
+    if (isArray !== undefined) {
+        merged.isArray = isArray;
+    }
+    const canSetOnCreate = inherited.canSetOnCreate === false ? false : (field.canSetOnCreate ?? inherited.canSetOnCreate);
+    if (canSetOnCreate !== undefined) {
+        merged.canSetOnCreate = canSetOnCreate;
+    }
+    const canSetOnUpdate = inherited.canSetOnUpdate === false ? false : (field.canSetOnUpdate ?? inherited.canSetOnUpdate);
+    if (canSetOnUpdate !== undefined) {
+        merged.canSetOnUpdate = canSetOnUpdate;
+    }
+    const nullable = inherited.nullable || field.nullable;
+    if (nullable !== undefined) {
+        merged.nullable = nullable;
+    }
+    return merged;
+}
+/**
+ * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ */
+export function findFieldByName(fields, fieldName, inheritedProperties = {}) {
+    const [baseFieldName, ...subFieldNames] = fieldName.split('.');
+    if (baseFieldName === undefined) {
+        return undefined;
+    }
+    let baseField;
+    if (baseFieldName.startsWith('semantic:')) {
+        baseField = findFieldBySemantic(fields, baseFieldName.substring('semantic:'.length));
+    }
+    else {
+        const unsanitizedBaseFieldName = unsanitizeFieldName(baseFieldName);
+        baseField = fields.find(field => field.name === unsanitizedBaseFieldName);
+    }
+    if (baseField) {
+        baseField = mergeInheritedProperties(baseField, inheritedProperties);
+        if (subFieldNames.length === 0) {
+            return baseField;
+        }
+        if (baseField.type === FieldValueTypes.OBJECT) {
+            return findFieldByName(baseField.fields, subFieldNames.join('.'), {
+                isArray: baseField.isArray,
+                canSetOnCreate: baseField.canSetOnCreate,
+                canSetOnUpdate: baseField.canSetOnUpdate,
+                nullable: baseField.nullable,
+            });
+        }
+        if (baseField.type === FieldValueTypes.REFERENCE) {
+            if (isRelationPointer(baseField.reference)) {
+                throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+            }
+            if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
+                subFieldNames.shift();
+            }
+            return findFieldByName(baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields, subFieldNames.join('.'), {
+                isArray: baseField.isArray,
+                canSetOnCreate: baseField.canSetOnCreate,
+                canSetOnUpdate: baseField.canSetOnUpdate,
+                nullable: baseField.nullable,
+            });
+        }
+        return undefined;
+    }
+    // If the dotted path lookup failed, try to find the field by its full name as is.
+    const unsanitizedFieldName = unsanitizeFieldName(fieldName);
+    return fields.find(field => field.name === unsanitizedFieldName);
+}
+/**
+ * Returns a field schema by its semantic.
+ *
+ * @throws Error if the found field does not respect the type constraints of its semantic.
+ */
+export function findFieldBySemantic(fields, semantic) {
+    const field = fields.find(field => field.semantic === semantic);
+    if (!field) {
+        return undefined;
+    }
+    validateSemanticFieldSchema(field);
+    return field;
+}

package/dist/src/index.cjs

@@ -102,9 +102,6 @@ const StatusCodes = {
  */
 const RelationSchemaDefaultValues = {
     CAN_READ_ITEM: true,
-    CAN_CREATE_ITEM: true,
-    CAN_UPDATE_ITEM: true,
-    CAN_DELETE_ITEM: false,
     CAN_ADD_FIELDS: false,
 };
 /**
@@ -682,7 +679,7 @@ const fieldTypeCompatibilityMatrix = {
         [FieldValueTypes.NUMBER]: {},
         [FieldValueTypes.OBJECT]: null,
         [FieldValueTypes.REFERENCE]: stringLikeToReferenceConfiguration,
-        [FieldValueTypes.RICH_TEXT]: {},
+        [FieldValueTypes.RICH_TEXT]: null,
         [FieldValueTypes.RICH_TEXT_HTML]: {},
         [FieldValueTypes.RICH_TEXT_MARKDOWN]: {},
         [FieldValueTypes.STRING]: {},
@@ -709,6 +706,313 @@ const fieldTypeCompatibilityMatrix = {
     },
 };
 
+/**
+ * Escapes characters that would otherwise break dotted field name path parsing.
+ */
+function sanitizeFieldName(fieldName) {
+    return fieldName.replaceAll('.', '__UNITO__DOT__').replaceAll('$', '__UNITO__DOLLAR__');
+}
+/**
+ * Reverses sanitizeFieldName.
+ */
+function unsanitizeFieldName(fieldName) {
+    return fieldName.replaceAll('__UNITO__DOT__', '.').replaceAll('__UNITO__DOLLAR__', '$');
+}
+/**
+ * Validates that a field schema received over the wire respects the type constraints of its semantic.
+ */
+function validateSemanticFieldSchema(field) {
+    if (field.semantic === Semantics.CREATED_AT || field.semantic === Semantics.UPDATED_AT) {
+        if (field.type !== FieldValueTypes.DATETIME) {
+            throw new Error(`Expected ${field.semantic} field to be a DATETIME, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected ${field.semantic} field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.DISPLAY_NAME) {
+        if (field.type !== FieldValueTypes.STRING && field.type !== FieldValueTypes.EMAIL) {
+            throw new Error(`Expected displayName field to be a STRING or EMAIL, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected displayName field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.PROVIDER_URL) {
+        if (field.type !== FieldValueTypes.URL) {
+            throw new Error(`Expected providerUrl field to be a URL, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected providerUrl field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.DESCRIPTION) {
+        if (field.type !== FieldValueTypes.STRING &&
+            field.type !== FieldValueTypes.RICH_TEXT_HTML &&
+            field.type !== FieldValueTypes.RICH_TEXT_MARKDOWN &&
+            field.type !== FieldValueTypes.RICH_TEXT) {
+            throw new Error(`Expected description field to be a STRING, RICH_TEXT_HTML, RICH_TEXT_MARKDOWN or RICH_TEXT, got ${field.type}`);
+        }
+        if (field.isArray) {
+            throw new Error(`Expected description field to be a single value, got an array`);
+        }
+    }
+    if (field.semantic === Semantics.IS_PUBLIC && field.type !== FieldValueTypes.BOOLEAN) {
+        throw new Error(`Expected isPublic field to be a BOOLEAN, got ${field.type}`);
+    }
+    if ((field.semantic === Semantics.USER || field.semantic === Semantics.PARENT) &&
+        field.type !== FieldValueTypes.REFERENCE) {
+        throw new Error(`Expected ${field.semantic} field to be a REFERENCE, got ${field.type}`);
+    }
+}
+/**
+ * Validates a value against a specific type.
+ */
+function validateFieldValueType(field, value) {
+    if (field.type === FieldValueTypes.STRING && typeof value !== 'string') {
+        throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.EMAIL) {
+        if (typeof value !== 'string') {
+            throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+        }
+        // Inspired by https://github.com/manishsaraan/email-validator/blob/master/index.js
+        const emailRegex = /^[-!#$%&'*+/0-9=?A-Z^_a-z`{|}~](\.?[-!#$%&'*+/0-9=?A-Z^_a-z`{|}~])*@[a-zA-Z0-9](-*\.?[a-zA-Z0-9])*\.[a-zA-Z](-?[a-zA-Z0-9])+$/;
+        if (!emailRegex.test(value)) {
+            throw new Error(`Expected ${field.name} to be a valid email address`);
+        }
+    }
+    if (field.type === FieldValueTypes.URL) {
+        if (typeof value !== 'string') {
+            throw new Error(`Expected ${field.name} to be a string, got ${typeof value}`);
+        }
+        try {
+            new URL(value.startsWith('http') ? value : `http://${value}`);
+        }
+        catch {
+            throw new Error(`Expected ${field.name} to be a valid URL`);
+        }
+    }
+    if (field.type === FieldValueTypes.NUMBER && typeof value !== 'number') {
+        throw new Error(`Expected ${field.name} to be a number, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.INTEGER) {
+        if (typeof value !== 'number') {
+            throw new Error(`Expected ${field.name} to be a number, got ${typeof value}`);
+        }
+        if (!Number.isInteger(value)) {
+            throw new Error(`Expected ${field.name} to be an integer, got ${value}`);
+        }
+    }
+    if (field.type === FieldValueTypes.BOOLEAN && typeof value !== 'boolean') {
+        throw new Error(`Expected ${field.name} to be a boolean, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.OBJECT && !isObject(value)) {
+        throw new Error(`Expected ${field.name} to be an object, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.REFERENCE && !isItemSummary(value)) {
+        throw new Error(`Expected ${field.name} to be an ItemSummary, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.DATETIME && (typeof value !== 'string' || isNaN(Date.parse(value)))) {
+        throw new Error(`Expected ${field.name} to be a valid ISO datetime string, got ${typeof value}`);
+    }
+    if (field.type === FieldValueTypes.DATE && (typeof value !== 'string' || isNaN(Date.parse(value)))) {
+        throw new Error(`Expected ${field.name} to be a valid ISO date string, got ${typeof value}`);
+    }
+}
+/**
+ * Validates a field value against its schema.
+ */
+function validateFieldValue(field, value) {
+    if (value === undefined) {
+        throw new Error(`Expected ${field.name} to be defined, got undefined`);
+    }
+    if (field.nullable === false && value === null) {
+        throw new Error(`Expected ${field.name} to be defined, got null`);
+    }
+    if (value === null) {
+        return;
+    }
+    if (field.isArray && !Array.isArray(value)) {
+        throw new Error(`Expected ${field.name} to be an array, got ${typeof value}`);
+    }
+    if (!field.isArray && Array.isArray(value)) {
+        throw new Error(`Expected ${field.name} to be a single value, got an array`);
+    }
+    if (Array.isArray(value)) {
+        for (const subvalue of value) {
+            validateFieldValueType(field, subvalue);
+        }
+    }
+    else {
+        validateFieldValueType(field, value);
+    }
+}
+/**
+ * Returns the validated value of a field, looking it up by name and falling back to its `semantic:` key.
+ *
+ * @throws Error if the value is invalid.
+ */
+function getUnsafeValue(field, values) {
+    let value = values[field.name];
+    if (value === undefined) {
+        if (field.semantic && `semantic:${field.semantic}` in values) {
+            value = values[`semantic:${field.semantic}`];
+        }
+    }
+    validateFieldValue(field, value);
+    return value;
+}
+/**
+ * Same as getUnsafeValue, but returns undefined instead of throwing on invalid values.
+ */
+function getSafeValue(field, values) {
+    try {
+        return getUnsafeValue(field, values);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Returns a field value by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ */
+function findValueByName(fields, values, fieldName) {
+    const [baseFieldName, ...subFieldNames] = fieldName.split('.');
+    if (baseFieldName === undefined) {
+        return undefined;
+    }
+    const baseField = findFieldByName(fields, baseFieldName);
+    if (!baseField) {
+        if (subFieldNames.length === 0) {
+            return undefined;
+        }
+        const literalField = findFieldByName(fields, fieldName);
+        return literalField ? getSafeValue(literalField, values) : undefined;
+    }
+    const baseFieldValue = getSafeValue(baseField, values);
+    if (subFieldNames.length === 0) {
+        return baseFieldValue;
+    }
+    if (baseField.type === FieldValueTypes.OBJECT) {
+        const subFieldName = subFieldNames.join('.');
+        if (isObject(baseFieldValue)) {
+            return findValueByName(baseField.fields, baseFieldValue, subFieldName);
+        }
+        if (Array.isArray(baseFieldValue)) {
+            return baseFieldValue
+                .map(value => (isObject(value) ? findValueByName(baseField.fields, value, subFieldName) : undefined))
+                .filter(value => value !== undefined);
+        }
+    }
+    if (baseField.type === FieldValueTypes.REFERENCE) {
+        if (isRelationPointer(baseField.reference)) {
+            throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+        }
+        if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
+            subFieldNames.shift();
+        }
+        const subFieldName = subFieldNames.join('.');
+        const referenceFields = baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields;
+        if (isItemSummary(baseFieldValue)) {
+            return findValueByName(referenceFields, baseFieldValue.fields ?? {}, subFieldName);
+        }
+        if (Array.isArray(baseFieldValue)) {
+            return baseFieldValue
+                .map(value => isItemSummary(value) ? findValueByName(referenceFields, value.fields ?? {}, subFieldName) : undefined)
+                .filter(value => value !== undefined);
+        }
+    }
+    return undefined;
+}
+/**
+ * Subfields inherit some of their parents' properties: a subfield of an array field yields multiple
+ * values, and a subfield of a read-only field cannot be written to.
+ */
+function mergeInheritedProperties(field, inherited) {
+    const merged = { ...field };
+    const isArray = inherited.isArray || field.isArray;
+    if (isArray !== undefined) {
+        merged.isArray = isArray;
+    }
+    const canSetOnCreate = inherited.canSetOnCreate === false ? false : (field.canSetOnCreate ?? inherited.canSetOnCreate);
+    if (canSetOnCreate !== undefined) {
+        merged.canSetOnCreate = canSetOnCreate;
+    }
+    const canSetOnUpdate = inherited.canSetOnUpdate === false ? false : (field.canSetOnUpdate ?? inherited.canSetOnUpdate);
+    if (canSetOnUpdate !== undefined) {
+        merged.canSetOnUpdate = canSetOnUpdate;
+    }
+    const nullable = inherited.nullable || field.nullable;
+    if (nullable !== undefined) {
+        merged.nullable = nullable;
+    }
+    return merged;
+}
+/**
+ * Returns a field schema by its name, traversing dotted paths through OBJECT and REFERENCE fields.
+ * Also accepts `semantic:` prefixed names and sanitized names (see sanitizeFieldName).
+ */
+function findFieldByName(fields, fieldName, inheritedProperties = {}) {
+    const [baseFieldName, ...subFieldNames] = fieldName.split('.');
+    if (baseFieldName === undefined) {
+        return undefined;
+    }
+    let baseField;
+    if (baseFieldName.startsWith('semantic:')) {
+        baseField = findFieldBySemantic(fields, baseFieldName.substring('semantic:'.length));
+    }
+    else {
+        const unsanitizedBaseFieldName = unsanitizeFieldName(baseFieldName);
+        baseField = fields.find(field => field.name === unsanitizedBaseFieldName);
+    }
+    if (baseField) {
+        baseField = mergeInheritedProperties(baseField, inheritedProperties);
+        if (subFieldNames.length === 0) {
+            return baseField;
+        }
+        if (baseField.type === FieldValueTypes.OBJECT) {
+            return findFieldByName(baseField.fields, subFieldNames.join('.'), {
+                isArray: baseField.isArray,
+                canSetOnCreate: baseField.canSetOnCreate,
+                canSetOnUpdate: baseField.canSetOnUpdate,
+                nullable: baseField.nullable,
+            });
+        }
+        if (baseField.type === FieldValueTypes.REFERENCE) {
+            if (isRelationPointer(baseField.reference)) {
+                throw new Error(`Reference field "${baseField.name}" is a relation pointer that was not populated`);
+            }
+            if (subFieldNames[0] === 'fields' && subFieldNames.length > 1) {
+                subFieldNames.shift();
+            }
+            return findFieldByName(baseField.reference.schema === '__self' ? fields : baseField.reference.schema.fields, subFieldNames.join('.'), {
+                isArray: baseField.isArray,
+                canSetOnCreate: baseField.canSetOnCreate,
+                canSetOnUpdate: baseField.canSetOnUpdate,
+                nullable: baseField.nullable,
+            });
+        }
+        return undefined;
+    }
+    // If the dotted path lookup failed, try to find the field by its full name as is.
+    const unsanitizedFieldName = unsanitizeFieldName(fieldName);
+    return fields.find(field => field.name === unsanitizedFieldName);
+}
+/**
+ * Returns a field schema by its semantic.
+ *
+ * @throws Error if the found field does not respect the type constraints of its semantic.
+ */
+function findFieldBySemantic(fields, semantic) {
+    const field = fields.find(field => field.semantic === semantic);
+    if (!field) {
+        return undefined;
+    }
+    validateSemanticFieldSchema(field);
+    return field;
+}
+
 /**
  * JSONPath parser that returns a relation that is guaranteed to have its schema populated.
  */
@@ -937,7 +1241,12 @@ exports.RichTextNodeTypes = RichTextNodeTypes;
 exports.Semantics = Semantics;
 exports.StatusCodes = StatusCodes;
 exports.fieldTypeCompatibilityMatrix = fieldTypeCompatibilityMatrix;
+exports.findFieldByName = findFieldByName;
+exports.findFieldBySemantic = findFieldBySemantic;
 exports.findRelationByJSONPath = findRelationByJSONPath;
+exports.findValueByName = findValueByName;
+exports.getSafeValue = getSafeValue;
+exports.getUnsafeValue = getUnsafeValue;
 exports.isFieldSchema = isFieldSchema;
 exports.isFieldValueType = isFieldValueType;
 exports.isItem = isItem;
@@ -953,3 +1262,5 @@ exports.isRichTextNodeType = isRichTextNodeType;
 exports.isSemantic = isSemantic;
 exports.isString = isString;
 exports.isUndefined = isUndefined;
+exports.sanitizeFieldName = sanitizeFieldName;
+exports.unsanitizeFieldName = unsanitizeFieldName;

package/dist/src/index.d.ts

@@ -1,5 +1,6 @@
 export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
+export * from './fieldHelpers.js';
 export * from './jsonPathHelpers.js';
 export * from './richText.js';

package/dist/src/index.js

@@ -2,5 +2,6 @@
 export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
+export * from './fieldHelpers.js';
 export * from './jsonPathHelpers.js';
 export * from './richText.js';

package/dist/src/types.d.ts

@@ -716,9 +716,6 @@ export type WebhookParseResponsePayload = WebhookParsedItem | WebhookItem | (Web
  */
 export declare const RelationSchemaDefaultValues: {
     readonly CAN_READ_ITEM: true;
-    readonly CAN_CREATE_ITEM: true;
-    readonly CAN_UPDATE_ITEM: true;
-    readonly CAN_DELETE_ITEM: false;
     readonly CAN_ADD_FIELDS: false;
 };
 /**

package/dist/src/types.js

@@ -100,9 +100,6 @@ export const StatusCodes = {
  */
 export const RelationSchemaDefaultValues = {
     CAN_READ_ITEM: true,
-    CAN_CREATE_ITEM: true,
-    CAN_UPDATE_ITEM: true,
-    CAN_DELETE_ITEM: false,
     CAN_ADD_FIELDS: false,
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unito/integration-api",
-  "version": "8.0.7",
+  "version": "8.0.9",
   "description": "The Unito Integration API",
   "type": "module",
   "types": "./dist/src/index.d.ts",