@unito/integration-api 5.0.1 → 7.0.0

package/dist/schemas/referenceRelation.json

@@ -3,7 +3,7 @@
   "title": "Relation",
   "type": "object",
   "additionalProperties": false,
-  "required": ["path", "schema", "label"],
+  "required": ["path", "schema", "label", "name"],
   "properties": {
     "path": {
       "type": "string",
@@ -25,8 +25,7 @@
       "type": "string",
       "pattern": "^[a-zA-Z0-9_-]*$",
       "minLength": 1,
-      "maxLength": 100,
-      "deprecated": true
+      "maxLength": 100
     },
     "schema": {
       "oneOf": [

package/dist/src/guards.js

@@ -53,6 +53,7 @@ export function isItem(potentialItem) {
  */
 export function isReferenceRelation(potentialReferenceRelation) {
     return (isObject(potentialReferenceRelation) &&
+        isString(potentialReferenceRelation['name']) &&
         isString(potentialReferenceRelation['path']) &&
         isString(potentialReferenceRelation['label']) &&
         isRelationSchemaOrSelf(potentialReferenceRelation['schema']));

package/dist/src/index.cjs

@@ -159,6 +159,7 @@ function isItem(potentialItem) {
  */
 function isReferenceRelation(potentialReferenceRelation) {
     return (isObject(potentialReferenceRelation) &&
+        isString(potentialReferenceRelation['name']) &&
         isString(potentialReferenceRelation['path']) &&
         isString(potentialReferenceRelation['label']) &&
         isRelationSchemaOrSelf(potentialReferenceRelation['schema']));

package/dist/src/types.d.ts

@@ -98,28 +98,63 @@ interface AbstractFieldSchema {
      */
     nullable?: boolean;
 }
-export interface BasicFieldSchema extends AbstractFieldSchema {
-    /**
-     * The type of the field.
-     */
-    type: Exclude<FieldValueType, typeof FieldValueTypes.BLOB | typeof FieldValueTypes.REFERENCE | typeof FieldValueTypes.OBJECT | typeof FieldValueTypes.DATETIME_RANGE | typeof FieldValueTypes.DATE_RANGE>;
+type BasicFieldValueType = Exclude<FieldValueType, typeof FieldValueTypes.BLOB | typeof FieldValueTypes.REFERENCE | typeof FieldValueTypes.OBJECT | typeof FieldValueTypes.DATETIME_RANGE | typeof FieldValueTypes.DATE_RANGE>;
+/**
+ * Semantic-constrained BasicFieldSchema variants.
+ * Each semantic restricts which field types are valid, matching the runtime
+ * validation in integrationDebugger's getSemanticSupportedFieldTypes().
+ */
+interface ProviderUrlFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.PROVIDER_URL;
+    type: typeof FieldValueTypes.URL;
+}
+interface CreatedAtFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.CREATED_AT;
+    type: typeof FieldValueTypes.DATETIME;
 }
+interface UpdatedAtFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.UPDATED_AT;
+    type: typeof FieldValueTypes.DATETIME;
+}
+interface DescriptionFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.DESCRIPTION;
+    type: typeof FieldValueTypes.RICH_TEXT_HTML | typeof FieldValueTypes.RICH_TEXT_MARKDOWN | typeof FieldValueTypes.STRING;
+}
+interface DisplayNameFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.DISPLAY_NAME;
+    type: typeof FieldValueTypes.STRING | typeof FieldValueTypes.EMAIL;
+}
+interface UnconstrainedBasicFieldSchema extends AbstractFieldSchema {
+    semantic?: never;
+    type: BasicFieldValueType;
+}
+export type BasicFieldSchema = ProviderUrlFieldSchema | CreatedAtFieldSchema | UpdatedAtFieldSchema | DescriptionFieldSchema | DisplayNameFieldSchema | UnconstrainedBasicFieldSchema;
 export interface BlobFieldSchema extends AbstractFieldSchema {
     /**
      * The type of the field.
      */
     type: typeof FieldValueTypes.BLOB;
 }
-export interface ReferenceFieldSchema extends AbstractFieldSchema {
-    /**
-     * The type of the field.
-     */
+/**
+ * Semantic-constrained ReferenceFieldSchema variants.
+ * USER and PARENT semantics must use REFERENCE type.
+ */
+interface UserReferenceFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.USER;
+    type: typeof FieldValueTypes.REFERENCE;
+    reference: ReferenceRelation;
+}
+interface ParentReferenceFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.PARENT;
+    type: typeof FieldValueTypes.REFERENCE;
+    reference: ReferenceRelation;
+}
+interface UnconstrainedReferenceFieldSchema extends AbstractFieldSchema {
+    semantic?: never;
     type: typeof FieldValueTypes.REFERENCE;
-    /**
-     * Describe the referenced collection.
-     */
     reference: ReferenceRelation;
 }
+export type ReferenceFieldSchema = UserReferenceFieldSchema | ParentReferenceFieldSchema | UnconstrainedReferenceFieldSchema;
 /**
  * A ReferenceRelation describes a relation that can be used in a ReferenceFieldSchema.
  */
@@ -141,10 +176,9 @@ export interface ReferenceRelation {
      */
     semantic?: RelationSemantic;
     /**
-     * The name for the reference relation.
-     * @deprecated Will be removed in a future version.
+     * The main identifier of the reference relation.
      */
-    name?: string;
+    name: string;
     /**
      * The shape of the relation.
      */
@@ -573,7 +607,16 @@ export interface WebhookParsedItem {
 }
 export interface WebhookItem {
     /**
-     * The canonical path of the parent item, if applicable.
+     * The canonical path of the parent item for this webhook event.
+     *
+     * Used as a fallback when the item's canonicalPath is not yet known to the platform
+     * (e.g., newly created items). In that case, sync-platform enqueues a sync job for
+     * the parent, which will discover the new child item during its scan.
+     *
+     * - If the exact parent is unknown without an extra API call, setting a grandparent
+     *   (e.g., a sheet or project) is acceptable — it triggers a broader scan that will
+     *   still pick up the new item.
+     * - If undefined and the item is not found, the webhook event is skipped entirely.
      */
     parentCanonicalPath?: string;
     /**

package/package.json

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