@runmorph/cdk v0.0.29

Morph – Connector Development Kit (CDK)

The Morph Connector Development Kit (CDK) is a powerful toolkit for building and managing unified third-party connectors. It provides developers with a robust set of tools and utilities to streamline the process of creating, testing, and deploying connectors for various services and platforms.

FieldMapper

The FieldMapper class is a utility for mapping fields between remote data sources and unified models. It handles reading field values from remote data and writing field values back to remote data.

Usage

import { FieldMapper, FieldType, createField } from "@runmorph/cdk";

// Example remote data type
interface HubspotContact {
  id: string;
  properties: {
    firstname: string;
    lastname: string;
    email: string;
    phone: string;
    jobtitle: string;
    company: string;
  };
}

// Create a field mapper for the firstName field
const firstNameField = new FieldMapper<HubspotContact>({
  key: "firstName",
  name: "First Name",
  description: "The contact's first name",
  required: true,
  type: FieldType.TEXT,
  read: (from) => from("properties.firstname"),
  write: (to) => to("properties.firstname"),
});

// Create a field mapper for a select field with options
const jobTitleField = createField<HubspotContact>({
  key: "jobTitle",
  name: "Job Title",
  description: "The contact's job title",
  type: FieldType.SELECT,
  options: [
    { label: "CEO", value: "ceo" },
    { label: "CTO", value: "cto" },
    { label: "Developer", value: "developer" },
  ],
  read: (from) => from("properties.jobtitle"),
  write: (to) => to("properties.jobtitle"),
});

// Example usage: Reading data
const hubspotContact: HubspotContact = {
  id: "12345",
  properties: {
    firstname: "John",
    lastname: "Doe",
    email: "john.doe@example.com",
    phone: "+1234567890",
    jobtitle: "cto",
    company: "Acme Inc.",
  },
};

const firstName = firstNameField.read(hubspotContact);
console.log(firstName); // "John"

const jobTitle = jobTitleField.read(hubspotContact);
console.log(jobTitle); // "cto"

// Example usage: Writing data
const firstNameUpdate = firstNameField.write("Jane");
console.log(firstNameUpdate); // { properties: { firstname: 'Jane' } }

const jobTitleUpdate = jobTitleField.write("developer");
console.log(jobTitleUpdate); // { properties: { jobtitle: 'developer' } }

Advanced Transformations

You can also apply transformations when reading from or writing to remote data:

// Create a field mapper with transformations
const dateField = new FieldMapper<HubspotContact>({
  key: "createdAt",
  name: "Created At",
  description: "The date when the contact was created",
  type: FieldType.DATE,
  read: (from) => from("properties.createdate", (value) => new Date(value)),
  write: (to) => to("properties.createdate", (value) => value.toISOString()),
});

// Create a field mapper for a boolean field with transformation
const isCustomerField = createField<HubspotContact>({
  key: "isCustomer",
  name: "Is Customer",
  description: "Whether the contact is a customer",
  type: FieldType.BOOLEAN,
  read: (from) =>
    from("properties.hs_is_customer", (value) => value === "true"),
  write: (to) =>
    to("properties.hs_is_customer", (value) => (value ? "true" : "false")),
});

Validation

You can add validation to fields using Zod schemas:

import { z } from "zod";

// Create a field mapper with validation
const emailField = new FieldMapper<HubspotContact>({
  key: "email",
  name: "Email",
  description: "The contact's email address",
  required: true,
  type: FieldType.TEXT,
  validation: z.string().email(),
  read: (from) => from("properties.email"),
  write: (to) => to("properties.email"),
});

// Validate an email
const isValid = emailField.validate("not-an-email"); // false
const isValidEmail = emailField.validate("user@example.com"); // true