@unito/integration-api 8.0.1 → 8.0.2

package/dist/schemas/definitions.json

@@ -24,6 +24,41 @@
         "url"
       ]
     },
+    "richTextNodeType": {
+      "$id": "RichTextNodeType",
+      "type": "string",
+      "enum": [
+        "blockquote",
+        "break",
+        "code",
+        "delete",
+        "emphasis",
+        "heading1",
+        "heading2",
+        "heading3",
+        "heading4",
+        "heading5",
+        "heading6",
+        "highlight",
+        "image",
+        "inlineCode",
+        "link",
+        "listItem",
+        "listOrdered",
+        "listUnordered",
+        "paragraph",
+        "reference",
+        "strong",
+        "subscript",
+        "superscript",
+        "table",
+        "tableCell",
+        "tableRow",
+        "text",
+        "thematicBreak",
+        "underline"
+      ]
+    },
     "semantic": {
       "$id": "Semantic",
       "type": ["string", "null"],

package/dist/schemas/fieldSchema.json

@@ -76,6 +76,12 @@
         "nullable": {
           "type": "boolean",
           "default": true
+        },
+        "supportedRichTextNodes": {
+          "type": "array",
+          "items": {
+            "$ref": "https://unito.io/integration_api/definitions.schema.json#/$defs/richTextNodeType"
+          }
         }
       }
     },

package/dist/src/index.cjs

@@ -873,11 +873,65 @@ function matchesFilter(item, filter) {
     return item[filter.property] === filter.value;
 }
 
+/**
+ * Published rich text node vocabulary, following the unist structural convention.
+ * Every node has `{ type, children?, value?, data? }`.
+ *
+ * Per-variant types are used where providers have real capability variance
+ * (e.g., heading depth support differs across providers; ordered and unordered
+ * lists are independent capabilities). Semantically-equivalent HTML synonyms
+ * collapse to the canonical type at parse time — `<b>`/`<strong>` yield
+ * `strong`, `<i>`/`<em>` yield `emphasis`, `<s>`/`<strike>`/`<del>` yield
+ * `delete`.
+ *
+ * Nodes whose `type` is not in this list are treated as custom-typed nodes by
+ * the Syncer and sentinel-encoded when the target doesn't declare support.
+ *
+ * Ref: https://github.com/unitoio/sync-services/issues/3239
+ */
+const RichTextNodeTypes = {
+    // Block
+    PARAGRAPH: 'paragraph',
+    HEADING_1: 'heading1',
+    HEADING_2: 'heading2',
+    HEADING_3: 'heading3',
+    HEADING_4: 'heading4',
+    HEADING_5: 'heading5',
+    HEADING_6: 'heading6',
+    BLOCKQUOTE: 'blockquote',
+    CODE: 'code',
+    LIST_ORDERED: 'listOrdered',
+    LIST_UNORDERED: 'listUnordered',
+    LIST_ITEM: 'listItem',
+    TABLE: 'table',
+    TABLE_ROW: 'tableRow',
+    TABLE_CELL: 'tableCell',
+    THEMATIC_BREAK: 'thematicBreak',
+    IMAGE: 'image',
+    BREAK: 'break',
+    // Inline
+    TEXT: 'text',
+    STRONG: 'strong',
+    EMPHASIS: 'emphasis',
+    UNDERLINE: 'underline',
+    INLINE_CODE: 'inlineCode',
+    DELETE: 'delete',
+    LINK: 'link',
+    SUPERSCRIPT: 'superscript',
+    SUBSCRIPT: 'subscript',
+    HIGHLIGHT: 'highlight',
+    REFERENCE: 'reference',
+};
+function isRichTextNodeType(value) {
+    return typeof value === 'string' && Object.values(RichTextNodeTypes).includes(value);
+}
+
 exports.FieldSchemaDefaultValues = FieldSchemaDefaultValues;
 exports.FieldValueTypes = FieldValueTypes;
 exports.OperatorTypes = OperatorTypes;
 exports.RelationSchemaDefaultValues = RelationSchemaDefaultValues;
 exports.RelationSemantics = RelationSemantics;
+exports.RichTextNodeTypes = RichTextNodeTypes;
 exports.Semantics = Semantics;
 exports.StatusCodes = StatusCodes;
 exports.fieldTypeCompatibilityMatrix = fieldTypeCompatibilityMatrix;
@@ -893,6 +947,7 @@ exports.isRelationPointer = isRelationPointer;
 exports.isRelationSchema = isRelationSchema;
 exports.isRelationSchemaOrSelf = isRelationSchemaOrSelf;
 exports.isRelationSummary = isRelationSummary;
+exports.isRichTextNodeType = isRichTextNodeType;
 exports.isSemantic = isSemantic;
 exports.isString = isString;
 exports.isUndefined = isUndefined;

package/dist/src/index.d.ts

@@ -2,3 +2,4 @@ export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
 export * from './jsonPathHelpers.js';
+export * from './richText.js';

package/dist/src/index.js

@@ -3,3 +3,4 @@ export * from './types.js';
 export * from './guards.js';
 export * from './compatibilities.js';
 export * from './jsonPathHelpers.js';
+export * from './richText.js';

package/dist/src/richText.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Published rich text node vocabulary, following the unist structural convention.
+ * Every node has `{ type, children?, value?, data? }`.
+ *
+ * Per-variant types are used where providers have real capability variance
+ * (e.g., heading depth support differs across providers; ordered and unordered
+ * lists are independent capabilities). Semantically-equivalent HTML synonyms
+ * collapse to the canonical type at parse time — `<b>`/`<strong>` yield
+ * `strong`, `<i>`/`<em>` yield `emphasis`, `<s>`/`<strike>`/`<del>` yield
+ * `delete`.
+ *
+ * Nodes whose `type` is not in this list are treated as custom-typed nodes by
+ * the Syncer and sentinel-encoded when the target doesn't declare support.
+ *
+ * Ref: https://github.com/unitoio/sync-services/issues/3239
+ */
+export declare const RichTextNodeTypes: {
+    readonly PARAGRAPH: "paragraph";
+    readonly HEADING_1: "heading1";
+    readonly HEADING_2: "heading2";
+    readonly HEADING_3: "heading3";
+    readonly HEADING_4: "heading4";
+    readonly HEADING_5: "heading5";
+    readonly HEADING_6: "heading6";
+    readonly BLOCKQUOTE: "blockquote";
+    readonly CODE: "code";
+    readonly LIST_ORDERED: "listOrdered";
+    readonly LIST_UNORDERED: "listUnordered";
+    readonly LIST_ITEM: "listItem";
+    readonly TABLE: "table";
+    readonly TABLE_ROW: "tableRow";
+    readonly TABLE_CELL: "tableCell";
+    readonly THEMATIC_BREAK: "thematicBreak";
+    readonly IMAGE: "image";
+    readonly BREAK: "break";
+    readonly TEXT: "text";
+    readonly STRONG: "strong";
+    readonly EMPHASIS: "emphasis";
+    readonly UNDERLINE: "underline";
+    readonly INLINE_CODE: "inlineCode";
+    readonly DELETE: "delete";
+    readonly LINK: "link";
+    readonly SUPERSCRIPT: "superscript";
+    readonly SUBSCRIPT: "subscript";
+    readonly HIGHLIGHT: "highlight";
+    readonly REFERENCE: "reference";
+};
+export type RichTextNodeType = (typeof RichTextNodeTypes)[keyof typeof RichTextNodeTypes];
+export interface RichTextNode {
+    type: string;
+    children?: RichTextNode[];
+    value?: string;
+    data?: Record<string, unknown>;
+}
+export interface RichTextRoot {
+    type: 'root';
+    children: RichTextNode[];
+}
+export declare function isRichTextNodeType(value: unknown): value is RichTextNodeType;

package/dist/src/richText.js

@@ -0,0 +1,52 @@
+/**
+ * Published rich text node vocabulary, following the unist structural convention.
+ * Every node has `{ type, children?, value?, data? }`.
+ *
+ * Per-variant types are used where providers have real capability variance
+ * (e.g., heading depth support differs across providers; ordered and unordered
+ * lists are independent capabilities). Semantically-equivalent HTML synonyms
+ * collapse to the canonical type at parse time — `<b>`/`<strong>` yield
+ * `strong`, `<i>`/`<em>` yield `emphasis`, `<s>`/`<strike>`/`<del>` yield
+ * `delete`.
+ *
+ * Nodes whose `type` is not in this list are treated as custom-typed nodes by
+ * the Syncer and sentinel-encoded when the target doesn't declare support.
+ *
+ * Ref: https://github.com/unitoio/sync-services/issues/3239
+ */
+export const RichTextNodeTypes = {
+    // Block
+    PARAGRAPH: 'paragraph',
+    HEADING_1: 'heading1',
+    HEADING_2: 'heading2',
+    HEADING_3: 'heading3',
+    HEADING_4: 'heading4',
+    HEADING_5: 'heading5',
+    HEADING_6: 'heading6',
+    BLOCKQUOTE: 'blockquote',
+    CODE: 'code',
+    LIST_ORDERED: 'listOrdered',
+    LIST_UNORDERED: 'listUnordered',
+    LIST_ITEM: 'listItem',
+    TABLE: 'table',
+    TABLE_ROW: 'tableRow',
+    TABLE_CELL: 'tableCell',
+    THEMATIC_BREAK: 'thematicBreak',
+    IMAGE: 'image',
+    BREAK: 'break',
+    // Inline
+    TEXT: 'text',
+    STRONG: 'strong',
+    EMPHASIS: 'emphasis',
+    UNDERLINE: 'underline',
+    INLINE_CODE: 'inlineCode',
+    DELETE: 'delete',
+    LINK: 'link',
+    SUPERSCRIPT: 'superscript',
+    SUBSCRIPT: 'subscript',
+    HIGHLIGHT: 'highlight',
+    REFERENCE: 'reference',
+};
+export function isRichTextNodeType(value) {
+    return typeof value === 'string' && Object.values(RichTextNodeTypes).includes(value);
+}

package/dist/src/types.d.ts

@@ -1,4 +1,5 @@
 import { Readable } from 'node:stream';
+import type { RichTextNodeType } from './richText.js';
 /**
  * A Collection represents a paginated list of ItemSummary available through a Relation.
  */
@@ -98,7 +99,7 @@ interface AbstractFieldSchema {
      */
     nullable?: boolean;
 }
-type BasicFieldValueType = 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 | typeof FieldValueTypes.RICH_TEXT>;
 /**
  * Semantic-constrained BasicFieldSchema variants.
  * Each semantic restricts which field types are valid, matching the runtime
@@ -244,10 +245,35 @@ export interface ObjectFieldSchema extends AbstractFieldSchema {
      */
     fields: FieldSchema[];
 }
+/**
+ * Semantic-constrained RichTextFieldSchema variants.
+ * DESCRIPTION is the only semantic that naturally applies to rich text; other
+ * semantics (USER, CREATED_AT, etc.) are tied to different field value types.
+ */
+interface DescriptionRichTextFieldSchema extends AbstractFieldSchema {
+    semantic: typeof Semantics.DESCRIPTION;
+    type: typeof FieldValueTypes.RICH_TEXT;
+    /**
+     * The published rich text node types this field can round-trip.
+     * `text` is mandatory. When omitted, a curated baseline applies (defined
+     * elsewhere in this package).
+     *
+     * Syncer keys off the target field's declaration to decide whether to
+     * pass nodes through or sentinel-encode them. Source-side declarations
+     * are descriptive and not enforced at runtime.
+     */
+    supportedRichTextNodes?: readonly ['text', ...RichTextNodeType[]];
+}
+interface UnconstrainedRichTextFieldSchema extends AbstractFieldSchema {
+    semantic?: never;
+    type: typeof FieldValueTypes.RICH_TEXT;
+    supportedRichTextNodes?: readonly ['text', ...RichTextNodeType[]];
+}
+export type RichTextFieldSchema = DescriptionRichTextFieldSchema | UnconstrainedRichTextFieldSchema;
 /**
  * A FieldSchema describes the shape of a field.
  */
-export type FieldSchema = BasicFieldSchema | BlobFieldSchema | ReferenceFieldSchema | ObjectFieldSchema | DateRangeFieldSchema | DatetimeRangeFieldSchema;
+export type FieldSchema = BasicFieldSchema | BlobFieldSchema | ReferenceFieldSchema | ObjectFieldSchema | DateRangeFieldSchema | DatetimeRangeFieldSchema | RichTextFieldSchema;
 /**
  * A FieldValueType determines the type of an item's value.
  * The type represents a unique scalar value such as a string or an integer.

package/package.json

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