Headless UI library

npm install @amp-labs/react
# or
yarn add @amp-labs/react

import {
  AmpersandProvider,     // Needed for all hooks and components in @amp-labs/react.
  InstallationProvider,  // Needed for headless hooks and functions.
} from "@amp-labs/react"

const options = {
  project: 'PROJECT', // Your Ampersand project name or ID

  // Pick one of the following authentication methods.
  apiKey: 'API_KEY',  // Ampersand API key (simple)
  // OR 
  getToken: async ({consumerRef, groupRef}) => {  // JWT Authentication (advanced)
    // Custom logic to fetch JWT token from your backend, e.g.
    return await getTokenFromMyBackend(consumerRef, groupRef);
    // See https://docs.withampersand.com/api/jwt-auth
  },
};

// Define variables that will be used for this code snippet and
// other code snippets on this page.
const integration = "my-salesforce-integration"; // Must match name in `amp.yaml`.
const provider = "salesforce";
const groupRef = "group-test-1";
const groupName = "Test Group";
const consumerRef = "consumer-test-1";
const consumerName = "Test Consumer";

function App() {
  return (
    <AmpersandProvider options={options}>
      <InstallationProvider
        integration={integration}
        groupRef={groupRef}
        groupName={groupName}
        consumerRef={consumerRef}
        consumerName={consumerName}
      >
        {/* Your custom component */}
        <MyComponent />
      </InstallationProvider>
    </AmpersandProvider>
  );
}

import { useConnection, ConnectProvider } from '@amp-labs/react';

function MyComponent() {
  const {
    connection, // Connection object
    error,
    isPending,
    isFetching,
    isError,
    isSuccess,
  } = useConnection();

  // Use these values to build your custom UI
  return (
    <div>
      {connection ? (
        {/* If there isn't a Connection, show prebuilt ConnectProvider component. */}
        <ConnectProvider
          provider={provider}
          consumerRef={consumerRef}
          groupRef={groupRef}
          onConnectSuccess={(connection) => {
            console.log("Connection successful:", connection);
          }}
          onDisconnectSuccess={(connection) => {
            console.log("Disconnection successful:", connection);
          }}
        />
      ) : (
        {/* If user is already connected, guide them through the rest of the configuration. */}
        <MyConfigurationComponent/>
      )}
    </div>
  );
}

import { useInstallation } from '@amp-labs/react';

function InstallationComponent() {
  const { installation } = useInstallation();

  return (
    <div>
      {installation ? (
        <div>You've successfully installed the integration!</div>
      ) : (
        <MyInstallationComponent/>
      )}
    </div>
  );
}

import { useInstallation } from '@amp-labs/react';

function ConfigDisplayComponent() {
  const { installation } = useInstallation();

  if (!installation) {
    return <div>No installation found</div>;
  }

  // Access the configuration from the installation
  const config = installation.config;

  // Use the config to build your custom UI
}

(params: {
  config: InstallationConfigContent;
  onSuccess?: (data: Installation) => void;
  onError?: (error: Error) => void;
  onSettled?: () => void;
}) => void;

import { useCreateInstallation } from '@amp-labs/react';

function InstallationForm() {
  const {
    createInstallation,
    isPending,
    error,
    errorMsg,
  } = useCreateInstallation();

  const handleSubmit = async (e) => {
    e.preventDefault();
    createInstallation({
      // Add your installation config here
      config: {
        read: {
          objects: {
            companies: {
              objectName: 'companies',
              selectedFieldsAuto: 'all', // Read all fields
            },
          },
        },
      },
      onSuccess: (data) => {
        console.log("Installation created", { installation: data });
      },
      onError: (error) => {
        console.error("Installation creation failed", { error });
      },
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <button
        type="submit"
        disabled={isPending}
      >
        {isPending ? 'Creating...' : 'Create Installation'}
      </button>
      {error && <div className="error">{errorMsg}</div>}
    </form>
  );
}

import { useManifest } from "@amp-labs/react";

const {
  getReadObjects: () => HydratedIntegrationObject[],  // Get all read objects from manifest (v2.12.1+)
  getReadObject: (objectName: string) => {
    object: HydratedIntegrationObject | null;
    getRequiredFields: () => HydratedIntegrationField[] | null;
    getOptionalFields: () => HydratedIntegrationField[] | null;
  },
  getCustomerFieldsForObject: (objectName: string) => {
    // Map of field names to field metadata.
    allFields: { [field: string]: FieldMetadata } | null;
    // Get a specific field's metadata.
    getField: (field: string) => FieldMetadata | null;
  },
  data: HydratedRevision | undefined,
  isPending: boolean,
  isFetching: boolean,
  isError: boolean,
  isSuccess: boolean,
  error: Error | null,
} = useManifest();

  const { getCustomerFieldsForObject } = useManifest();

  // Get all the fields that exist on the customer's Account object,
  // including standard and custom fields.
  const fields = getCustomerFieldsForObject("account");

  // This is a map of field names to field metadata,
  const allFields = fields?.allFields;

  // Convert to array if you want to show all of them in a list.
  const allFieldsArray = allFields ? Object.values(allFields) : [];

const { getReadObjects } = useManifest();

const allReadObjects = getReadObjects(); // HydratedIntegrationObject[]

allReadObjects.forEach((obj) => {
  console.log(obj.objectName);
});

// Return values of `useLocalConfig` hook.
{
  draft: InstallationConfigContent;  // Current draft configuration
  get: () => InstallationConfigContent;  // Get current configuration
  reset: () => void;  // Reset to installation's current config
  setDraft: (config: InstallationConfigContent) => void;  // Update draft config
  removeObject: (objectName: string) => void;  // Remove object from all actions (v2.12.1+)
  readObject: (objectName: string) => ReadObjectHandlers;  // Manage read object config
  writeObject: (objectName: string) => WriteObjectHandlers;  // Manage write object config
}

// Shape of ReadObjectHandlers (returned by `readObject` function above).
{
  object: BaseReadConfigObject | undefined;  // Current read object configuration
  setEnableRead: () => void;  // Enable reading for object, initializes with defaults (v2.12.1+)
  setDisableRead: () => void;  // Disable reading for object (v2.12.1+)
  getSelectedField: (fieldName: string) => boolean;  // Check if field is selected
  setSelectedField: (params: { fieldName: string; selected: boolean }) => void;  // Toggle field selection
  getFieldMapping: (fieldName: string) => string | undefined;  // Get field mapping
  setFieldMapping: (params: { fieldName: string; mapToName: string }) => void;  // Set field mapping
  deleteFieldMapping: (mapToName: string) => void;  // Delete field mapping
}

// Shape of WriteObjectHandlers (returned by `writeObject` function above).
{
  object: BaseWriteConfigObject | undefined;  // Current write object configuration
  setEnableWrite: () => void;  // Enable write for object
  setDisableWrite: () => void;  // Disable write for object
  setEnableDeletion: () => void;  // Enable deletion for object
  setDisableDeletion: () => void;  // Disable deletion for object
  getWriteObject: () => BaseWriteConfigObject | undefined;  // Get write object config
   // advanced write features
  // https://docs.withampersand.com/write-actions#advanced-use-cases
  getDefaultValues: (fieldName: string) => FieldSettingDefault | undefined;
  setDefaultValues: (params: {
    fieldName: string;
    value: FieldSettingDefault;
  }) => void;
  getWriteOnCreateSetting: (
    fieldName: string,
  ) => FieldSettingWriteOnCreateEnum | undefined;
  setWriteOnCreateSetting: (params: {
    fieldName: string;
    value: FieldSettingWriteOnCreateEnum;
  }) => void;
  getWriteOnUpdateSetting: (
    fieldName: string,
  ) => FieldSettingWriteOnUpdateEnum | undefined;
  setWriteOnUpdateSetting: (params: {
    fieldName: string;
    value: FieldSettingWriteOnUpdateEnum;
  }) => void;
  getSelectedFieldSettings: (fieldName: string) => FieldSetting | undefined;
  setSelectedFieldSettings: (params: {
    fieldName: string;
    settings: FieldSetting;
  }) => void;
}

function ConfigManager() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  
  config.setDraft({
    provider: "salesforce",
    read: {
      objects: {
        contact: {
          objectName: "contact",
          selectedFields: {
            "name": true,
            "email": true
          },
          selectedFieldsMappings: {
            // Mapping from billingaddress (in SaaS API) to address (in your application).
            "address": "billingaddress"
          }
        }
      }
    }
  });

  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };

  return (<button onClick={handleSave}>Create installation</button>)
}

function ReadObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactConfig = config.readObject("contact");
  
  // Check if field is already selected in local config
  const isNameSelected = contactConfig.getSelectedField("name");
  
  // Select a field
  contactConfig.setSelectedField({ fieldName: "email", selected: true });
  
  // Get existing mapping for a field in local config
  const mappedField = contactConfig.getFieldMapping("email_address");

  // Set field mapping
  contactConfig.setFieldMapping({ 
    fieldName: "email", // raw field from provider API
    mapToName: "email_address" // mapped field
  });
  
  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}

function ObjectManager() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();

  // Enable reading for the "contact" and "account" objects
  config.readObject("contact").setEnableRead();
  config.readObject("account").setEnableRead();

  // Pause reads for "account" (keeps its config intact)
  config.readObject("account").setDisableRead();

  // Or fully remove "account" from both read and write config
  config.removeObject("account");

  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };

  return (<button onClick={handleSave}>Create installation</button>)
}

function WriteObjectConfig() {
  const { createInstallation } = useCreateInstallation();
  const config = useLocalConfig();
  const contactWriteConfig = config.writeObject("contact");
  
  // Enable write for Contact object
  contactWriteConfig.setEnableWrite();

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}

function WriteObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactWriteConfig = config.writeObject("contact");
  
  // Set default value for a field
  contactWriteConfig.setDefaultValues({
    fieldName: "source",
    value: {
      stringValue: "myApp"  // String default
    }
  });
  
  contactWriteConfig.setDefaultValues({
    fieldName: "amount",
    value: {
      integerValue: 0  // Number default
    }
  });
  
  contactWriteConfig.setDefaultValues({
    fieldName: "automated",
    value: {
      booleanValue: true  // Boolean default
    }
  });
  
  // Configure which fields should be written to during create operations
  contactWriteConfig.setWriteOnCreateSetting({
    fieldName: "source",
    value: "always"  // Always write source field on create
  });
  
  contactWriteConfig.setWriteOnCreateSetting({
    fieldName: "notes",
    value: "never"  // Never write notes field on create
  });
  
  // Configure which fields should be written to during update operations
  contactWriteConfig.setWriteOnUpdateSetting({
    fieldName: "source",
    value: "never"  // Never write source field on update
  });
  
  contactWriteConfig.setWriteOnUpdateSetting({
    fieldName: "notes",
    value: "always"  // Always write notes field on update
  });
  
  // Get current local settings
  const defaultValues = contactWriteConfig.getDefaultValues("source");
  const writeOnCreate = contactWriteConfig.getWriteOnCreateSetting("source");
  const writeOnUpdate = contactWriteConfig.getWriteOnUpdateSetting("source");

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}

function WriteObjectConfig() {
  const config = useLocalConfig();
  const { createInstallation } = useCreateInstallation();
  const contactWriteConfig = config.writeObject("contact");
  
  // Configure a field with both write behavior and default value
  contactWriteConfig.setFieldSettings({
    fieldName: "customSource",
    settings: {
      writeOnCreate: "always",  // Write on create
      writeOnUpdate: "never",   // Don't write on update
      default: {
        stringValue: "myApp"    // Default value
      }
    }
  });

  // Get current settings
  const current = contactWriteConfig.getFieldSettings("customSource");

  // Create an installation with the current config
  const handleSave = async () => {
    await createInstallation({
      config: config.get(),
    });
  };
}

const config = useLocalConfig();

// Per-object read handlers encapsulate initialization, default-seeding, and selection.
const contact = config.readObject("contact");
const isEmailSelected = contact.getSelectedField("email");
contact.setSelectedField({ fieldName: "email", selected: true });
contact.setFieldMapping({ fieldName: "email", mapToName: "email_address" });

// Per-object write handlers do the same for write config.
const contactWrite = config.writeObject("contact");
contactWrite.setEnableWrite();

// Snapshot for save. Revert to the installation's saved state.
const configToSave = config.get();
config.reset();

import {
  AmpersandProvider, ConnectProvider, useConnection, useInstallation,
} from '@amp-labs/react';

import { ConfigContent, AmpersandProviderOptions } from '@amp-labs/react/types';

const projectOptions: AmpersandProviderOptions ={
  apiKey: 'my-api-key',
  project: 'my-project',
}

const installationParams = {
  integration: 'my-hubspot-integration',
  consumerRef: 'user-123',
  groupRef: 'company-456',
};

export function App() {
  // Wrap your custom component inside of AmpersandProvider and InstallationProvider
  return (
    <AmpersandProvider options={projectOptions}>
      <InstallationProvider
        integration={installationParams.integration}
        consumerRef={installationParams.consumerRef}
        groupRef={installationParams.groupRef}
      >
        <MyIntegrationComponent />
      </InstallationProvider>
    </AmpersandProvider>
  );
}

// Static content for the installation, no user input needed
const myConfig: ConfigContent = {
  read: {
    objects: {
      companies: {
        objectName: 'companies',
        // Auto-select all fields to be read,
        // alternatively you can specify any desired fields & mappings here.
        selectedFieldsAuto: 'all',
      },
    }
};

function MyIntegrationComponent() {
  const {
    installation,
    isPending: isInstallationPending, // No data yet
    isFetching: isInstallationFetching, // Data is being refreshed
    isError: isInstallationError,
    error: installationError,
  } = useInstallation();
  
  const {
    connection,
    isPending: isConnectionPending, // No data yet
    isFetching: isConnectionFetching, // Data is being refreshed
    isError: isConnectionError,
    error: connectionError,
  } = useConnection(); 

  // Custom connection loading, error, and installation state overrides
  if (isConnectionPending || isInstallationPending) return <div>Loading </div>;
  if (isConnectionError) return <div>Error loading connection: {connectionError.message}</div>;
  if (isInstallationError) return <div>Error loading installation: {installationError.message}</div>;

  // The installation already exists
  if (!!installation) { return (<MyManageInstallationComponent />) } 

  if (connection) {
     createInstallation({ config: myConfig });
  };

  // Use Ampersand's built in UI for the Connection flow
  // This is the same as the existing ConnectProvider component but parameters
  // can be ommited since we are inside of InstallationProvider
  // When the connection is successful, this component will re-render since
  // `useConnection` will return the new connection.
  return (
     <ConnectProvider
        consumerRef={installationParams.consumerRef}
        groupRef={installationParams.groupRef}
     />
  );
}