### Action: surecontact_integration_loaded

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

This action fires after each integration instance is created. Use it to inspect or further configure integrations, or to attach cross-integration behavior.

```php
/**
 * @param string                                      $slug     Integration slug.
 * @param \SureContact\Integrations\Base_Integration $instance Integration instance.
 */
do_action( 'surecontact_integration_loaded', $slug, $instance );
```

--------------------------------

### Action: surecontact_integration_loaded

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Fires after each individual integration instance is created. Useful for inspecting or configuring a specific integration after it has been loaded.

```APIDOC
## Action: surecontact_integration_loaded

### Description
Fires after an individual integration instance is created. Useful for inspecting or configuring a specific integration after it has been loaded.

### Method
`do_action`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **slug** (string) - Required - The slug of the integration that was just loaded.
* **instance** (object) - Required - The instance of the loaded integration (object of type \SureContact\Integrations\Base_Integration).

### Request Example
```php
add_action( 'surecontact_integration_loaded', function( string $slug, \SureContact\Integrations\Base_Integration $instance ) {
    if ( 'my_custom_integration' === $slug ) {
        // Perform specific actions for my_custom_integration
        // e.g., $instance->set_custom_setting('some_value');
    }
}, 10, 2 );
```

### Response
This is an action hook and does not return a value.
```

--------------------------------

### Provide Per-Item Configuration Fields in PHP

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Implement `get_item_config_fields()` to expose per-item configuration fields for the rule editor. This method can branch logic based on the provided event key.

```php
/**
 * Return event‑specific configuration fields for a given item.
 *
 * @param string      $item_id Item ID (e.g. form ID).
 * @param string|null $event   Event key (e.g. 'submitted').
 * @return array
 */
public function get_item_config_fields( $item_id, $event = null ) {
	unset( $item_id ); // Use in your own implementation.

	// Example for a single event; you can branch by $event.
	return array(
		'add_lists' => array(
			'label'       => __( 'Add to Lists', 'surecontact' ),
			'description' => __( 'Lists to add contacts to when this event fires.', 'surecontact' ),
			'type'        => 'list-select',
			'default'     => array(),
		),
		'add_tags'  => array(
			'label'       => __( 'Add Tags', 'surecontact' ),
			'description' => __( 'Tags to add when this event fires.', 'surecontact' ),
			'type'        => 'tag-select',
			'default'     => array(),
		),
	);
}
```

--------------------------------

### Minimal SureContact Integration Skeleton

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Provides the basic structure for a SureContact integration class. Ensure `parent::__construct()` is called to initialize core services and enable the integration.

```php
<?php
namespace MyAddon;

use SureContact\Integrations\Base_Integration;

class SureContact_Integration extends Base_Integration {

	public function __construct() {
		// Slug MUST match the key used in surecontact_available_integrations.
		$this->slug        = 'my_addon';
		$this->name        = 'My Addon';
		$this->description = 'Syncs My Addon events and contacts to SureContact CRM.';
		$this->docs_url    = 'https://example.com/docs/my-addon-surecontact';
		$this->icon_url    = plugin_dir_url( __DIR__ ) . 'assets/icons/my-addon.svg';

		// Optional: a class or function that must exist for this integration
		// to be considered active on the filesystem level.
		$this->dependency  = 'MyAddon\\Plugin';

		parent::__construct();
	}

	/**
	 * Initialize all hooks for this integration.
	 *
	 * This method is called ONLY when the integration is enabled in SureContact.
	 */
	protected function init() {
		// Example: listen to your plugin's events.
		add_action( 'my_addon_form_submitted', array( $this, 'handle_form_submission' ), 10, 2 );
	}

	/**
	 * Handle a form submission (example).
	 *
	 * @param array $submission Raw submission data from your plugin.
	 * @param int   $user_id    Related WordPress user ID (0 if not applicable).
	 */
	public function handle_form_submission( $submission, $user_id = 0 ) {
		// 1) Build or normalize data into SureContact CRM format.
		$data = $this->build_crm_data(
			array(
				'email'      => $submission['email'] ?? '',
				'first_name' => $submission['first_name'] ?? '',
				'last_name'  => $submission['last_name'] ?? '',
			),
			array(
				'my_custom_field' => $submission['custom'] ?? '',
			),
			array(
				'source_form_id' => $submission['form_id'] ?? '',
			)
		);

		// 2) Optionally pass lists/tags/context from your own settings or logic.
		$context = array(
			'list_uuids' => array(), // e.g. mapped from your own config.
			'tag_uuids'  => array(),
		);

		// 3) Send to SureContact CRM (queues or immediate send handled by Contact_Service).
		$result = $this->send_to_crm( $data, $user_id, $context );

		// 4) Optional: handle WP_Error or success for logging.
		if ( is_wp_error( $result ) ) {
			// Your own logging or error handling.
			return;
		}
	}
}

```

--------------------------------

### Action: surecontact_integrations_loaded

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

This action fires after all integrations have been processed. It's useful for performing logic that depends on the full set of loaded integrations or for diagnostics.

```php
/**
 * @param array<string, \SureContact\Integrations\Base_Integration> $loaded_integrations
 */
do_action( 'surecontact_integrations_loaded', $loaded_integrations );
```

--------------------------------

### Action: surecontact_integrations_loaded

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Fires after all integrations have been processed. Ideal for logic that depends on the complete set of loaded integrations.

```APIDOC
## Action: surecontact_integrations_loaded

### Description
Fires after all integrations have been processed. Useful for performing logic that depends on the full set of loaded integrations or for diagnostics.

### Method
`do_action`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **loaded_integrations** (array<string, object>) - Required - An associative array where keys are integration slugs and values are their respective instances.

### Request Example
```php
add_action( 'surecontact_integrations_loaded', function( array $loaded_integrations ) {
    // Check if a specific integration is loaded
    if ( isset( $loaded_integrations['my_custom_integration'] ) ) {
        // Perform actions based on the presence of my_custom_integration
    }
    // Perform diagnostics on all loaded integrations
    foreach ( $loaded_integrations as $slug => $instance ) {
        // ...
    }
}, 10, 1 );
```

### Response
This is an action hook and does not return a value.
```

--------------------------------

### Filter: surecontact_available_integrations

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Use this filter to register or modify available integrations. It receives an associative array of slug => config and should return a modified array.

```php
/**
 * @param array $integrations Associative array of slug => config.
 * @return array
 */
apply_filters( 'surecontact_available_integrations', $integrations );
```

--------------------------------

### Provide Item Lists (Forms) in PHP

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Implement the `get_forms()` method to return all forms for your integration. Each item must include 'id', 'title', and 'type'. This method is discovered by the REST API via `method_exists()`.

```php
/**
 * Return all forms for this integration.
 *
 * Each item should have at least: id, title, and type.
 *
 * @return array
 */
public function get_forms() {
	$forms = array();

	// Replace this with your own form retrieval logic.
	foreach ( my_addon_get_forms() as $form ) {
		$forms[] = array(
			'id'    => (string) $form->id,
			'title' => $form->title,
			'type'  => 'form',
		);
	}

	return $forms;
}
```

--------------------------------

### Register Custom SureContact Integration

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Use this filter in your main plugin file to register a new integration. Ensure the class path and dependency are correctly set.

```php
add_filter( 'surecontact_available_integrations', function( $integrations ) {
	$integrations['my_addon'] = array(
		// Human‑readable name shown in the Integrations UI.
		'name'        => 'My Addon',

		// Fully-qualified PHP class name that extends SureContact\Integrations\Base_Integration.
		'class'       => 'MyAddon\\SureContact_Integration',

		// Absolute path to your integration class file.
		// External integrations SHOULD use "file_path" instead of "file".
		'file_path'   => plugin_dir_path( __FILE__ ) . 'includes/class-surecontact-integration.php',

		// A class or function name that indicates your plugin is active.
		// SureContact only attempts to load the integration if this exists.
		'dependency'  => 'MyAddon\\Plugin',

		// WordPress plugin basename for your main plugin.
		// Used by SureContact to show activation/install hints and to auto‑activate via REST.
		'plugin_file' => 'my-addon/my-addon.php',

		// Optional: URL to an icon for the Integrations UI (e.g. SVG or PNG).
		// If omitted, the UI falls back to initials (first 2 letters of the name).
		'icon_url'    => plugin_dir_url( __FILE__ ) . 'assets/icons/my-addon.svg',
	);

	return $integrations;
} );
```

--------------------------------

### Declare Events Per Item Type for Rule Engine UI

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Implement `get_events_by_item_type()` to specify the events associated with each item type. These keys are used by the rule engine UI, the integrations DB, and your logic.

```php
public function get_events_by_item_type( $item_type ) {
	if ( 'form' === $item_type ) {
		return array(
			array(
				'key'   => 'submitted',
				'label' => __( 'Form Submitted', 'surecontact' ),
			),
		);
	}

	if ( 'campaign' === $item_type ) {
		return array(
			array(
				'key'   => 'started',
				'label' => __( 'Campaign Started', 'surecontact' ),
			),
			array(
				'key'   => 'completed',
				'label' => __( 'Campaign Completed', 'surecontact' ),
			),
		);
	}

	return array();
}

```

--------------------------------

### Provide Field Definitions for Item Mapping in PHP

Source: https://surecontact.com/docs/third-party-integration-step-by-step-guide

Implement `get_item_fields()` to return fields for a specific item, used in the field mapping UI. If this method is absent, the fields endpoint returns a `WP_Error`.

```php
/**
 * Return fields for a specific item (for field mapping UI).
 *
 * @param string $item_id Item ID.
 * @return array
 */
public function get_item_fields( $item_id ) {
	// Example structure:
	return array(
		array(
			'key'   => 'email',
			'label' => __( 'Email', 'surecontact' ),
			'type'  => 'email',
		),
		array(
			'key'   => 'first_name',
			'label' => __( 'First Name', 'surecontact' ),
			'type'  => 'text',
		),
		// ...
	);
}
```