# `PhoenixKitEntities.Mirror.Importer`
[🔗](https://github.com/BeamLabEU/phoenix_kit_entities/blob/v0.4.6/lib/phoenix_kit_entities/mirror/importer.ex#L1)

Handles import of entities and entity data from JSON files with conflict resolution.

Each JSON file contains both the entity definition and all its data records.

## File Format

    {
      "export_version": "1.0",
      "exported_at": "2025-12-11T10:30:00Z",
      "definition": { ... entity schema ... },
      "data": [ ... array of data records ... ]
    }

## Conflict Strategies

- `:skip` - Skip import if record already exists (default)
- `:overwrite` - Replace existing record with imported data
- `:merge` - Merge imported data with existing record (keeps existing values where new is nil)

## Conflict Detection

- Entity definitions: matched by `name` field
- Entity data records: matched by `entity_name` + `slug`

# `conflict_strategy`

```elixir
@type conflict_strategy() :: :skip | :overwrite | :merge
```

# `import_result`

```elixir
@type import_result() ::
  {:ok, :created, any()}
  | {:ok, :updated, any()}
  | {:ok, :skipped, any()}
  | {:error, term()}
```

# `detect_conflicts`

```elixir
@spec detect_conflicts() :: map()
```

Detects all conflicts that would occur during import.

## Returns
  - `%{entity_conflicts: [...], data_conflicts: [...]}`

# `import_all`

```elixir
@spec import_all(conflict_strategy()) :: {:ok, map()}
```

Imports all entities from the mirror directory.

## Parameters
  - `strategy` - Conflict resolution strategy (default: :skip)

## Returns
  - `{:ok, %{definitions: [...], data: [...]}}`

# `import_entity`

```elixir
@spec import_entity(String.t(), conflict_strategy()) ::
  {:ok, map()} | {:error, term()}
```

Imports an entity (definition + data) from a JSON file.

## Parameters
  - `entity_name` - The entity name (file name without .json)
  - `strategy` - Conflict resolution strategy (default: :skip)

## Returns
  - `{:ok, %{definition: result, data: [results]}}` on success
  - `{:error, reason}` on failure

# `import_from_data`

```elixir
@spec import_from_data(map(), conflict_strategy()) :: {:ok, map()} | {:error, term()}
```

Imports from parsed JSON data (definition + data).

# `import_selected`

```elixir
@spec import_selected(map()) :: {:ok, map()}
```

Imports selected entities and records based on user selections.

## Parameters
  - `selections` - Map of entity_name => %{definition: action, data: %{slug => action}}
    where action is :skip, :overwrite, or :merge

## Example

    selections = %{
      "brand" => %{
        definition: :overwrite,
        data: %{
          "acme-corp" => :overwrite,
          "globex" => :skip
        }
      }
    }

## Returns
  - `{:ok, %{definitions: [...], data: [...]}}`

# `preview_import`

```elixir
@spec preview_import() :: map()
```

Previews what would be imported without making any changes.

Returns data grouped by entity for the import UI, with each entity containing
its definition preview and all data record previews.

## Returns

    %{
      entities: [
        %{
          name: "brand",
          definition: %{name: "brand", action: :create | :identical | :conflict},
          data: [%{slug: "acme", action: :create | :identical | :conflict}, ...]
        },
        ...
      ],
      summary: %{
        definitions: %{total: N, new: N, identical: N, conflicts: N},
        data: %{total: N, new: N, identical: N, conflicts: N}
      }
    }

---

*Consult [api-reference.md](api-reference.md) for complete listing*