data_porter 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f4f148347707854fe641913e1e21616ca6ed93b8e6c5ddcd0afb2421ddba7dc
-  data.tar.gz: e1ac18c356d7edcca901c54f1349d003e5a9b31d9feca5aed1ac51717402bbeb
+  metadata.gz: 7ca6bfabfc9f831d71c60a1942516a5dccf95c85e3787f16a1217188c9feb3a0
+  data.tar.gz: f703da9261612953fcacad2674e38bef3037b804191e7fb3087577846b096461
 SHA512:
-  metadata.gz: 4e96e22590744496c31aa51060cb1c043365eabbcefa9d17f97edc8eba18ae045fd598a6483aa57fad35b3524b120a2ee358c3103a36fbc44f595ff5eda23bc8
-  data.tar.gz: 5dbc857197bafd89108528aa95ee12617c5ee7e09b9784bbeb924442d11e07300f469a53d72ec44c0c39099836d2b24ac9a7d616422ddbc7d68fcbcbc06606f4
+  metadata.gz: a7d8ad32cb5d80e027d9adfe2a089a84703c6e8e5b00901c0d057a4b2bb24cb2ffbe0f6edb53f61021219fd03384830517192657fbe4c693dd74b6977279b22a
+  data.tar.gz: 6d96ecefa39d191cea801ff8e4075f5c9bb4e13979f7754041db33a6685701d98f4521230500a1d0a47a417ce141f1b08973b5cbfd65868b0c3920c99afb61f6

data/CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.2] - 2026-02-07
+
+### Changed
+
+- Exclude `docs/` from gem package (194 KB → 80 KB)
+
 ## [1.0.1] - 2026-02-07
 
 ### Added

data/lib/data_porter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataPorter
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_porter
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Seryl Lounis
@@ -139,16 +139,6 @@ files:
 - app/views/data_porter/mapping_templates/new.html.erb
 - app/views/layouts/data_porter/application.html.erb
 - config/routes.rb
-- docs/CONFIGURATION.md
-- docs/MAPPING.md
-- docs/ROADMAP.md
-- docs/SOURCES.md
-- docs/TARGETS.md
-- docs/screenshots/index-with-previewing.jpg
-- docs/screenshots/index.jpg
-- docs/screenshots/mapping.jpg
-- docs/screenshots/modal-new-import.jpg
-- docs/screenshots/preview.jpg
 - lib/data_porter.rb
 - lib/data_porter/broadcaster.rb
 - lib/data_porter/components.rb

data/docs/CONFIGURATION.md

@@ -1,115 +0,0 @@
-# Configuration
-
-All options are set in `config/initializers/data_porter.rb`:
-
-```ruby
-DataPorter.configure do |config|
-  # Parent controller for the engine's controllers to inherit from.
-  # Controls authentication, layouts, and helpers.
-  config.parent_controller = "ApplicationController"
-
-  # ActiveJob queue name for import jobs.
-  config.queue_name = :imports
-
-  # ActiveStorage service for uploaded files.
-  config.storage_service = :local
-
-  # ActionCable channel prefix.
-  config.cable_channel_prefix = "data_porter"
-
-  # Context builder: inject business data into targets.
-  # Receives the DataImport record.
-  config.context_builder = ->(data_import) {
-    { user: data_import.user }
-  }
-
-  # Maximum number of records displayed in preview.
-  config.preview_limit = 500
-
-  # Enabled source types.
-  config.enabled_sources = %i[csv json api xlsx]
-
-  # Auto-purge completed/failed imports older than this duration.
-  # Set to nil to disable. Run `rake data_porter:purge` manually or via cron.
-  config.purge_after = 60.days
-
-  # Maximum file size for uploads (default: 10 MB).
-  config.max_file_size = 10.megabytes
-
-  # Maximum number of records per import (default: 10,000).
-  # Set to nil to disable.
-  config.max_records = 10_000
-
-  # Transaction mode for imports.
-  # :per_record -- each record persisted independently (default)
-  # :all -- single transaction, rolls back entirely on any failure
-  config.transaction_mode = :per_record
-end
-```
-
-## Options reference
-
-| Option | Default | Description |
-|---|---|---|
-| `parent_controller` | `"ApplicationController"` | Controller class the engine inherits from |
-| `queue_name` | `:imports` | ActiveJob queue for import jobs |
-| `storage_service` | `:local` | ActiveStorage service name |
-| `cable_channel_prefix` | `"data_porter"` | ActionCable stream prefix |
-| `context_builder` | `nil` | Lambda receiving the DataImport record, returns context passed to target methods |
-| `preview_limit` | `500` | Max records shown in the preview step |
-| `enabled_sources` | `%i[csv json api xlsx]` | Source types available in the UI |
-| `purge_after` | `60.days` | Auto-purge completed/failed imports older than this duration |
-| `max_file_size` | `10.megabytes` | Maximum file size for uploads |
-| `max_records` | `10_000` | Maximum number of records per import (nil to disable) |
-| `transaction_mode` | `:per_record` | `:per_record` or `:all` (single transaction rollback) |
-
-## Authentication
-
-The engine inherits authentication from `parent_controller`. Set it to your authenticated base controller:
-
-```ruby
-config.parent_controller = "Admin::BaseController"
-```
-
-All engine routes will require the same authentication as your base controller.
-
-## Context builder
-
-The `context_builder` lambda lets you inject business data (current user, tenant, permissions) into target methods (`persist`, `after_import`, `on_error`). It receives the `DataImport` record:
-
-```ruby
-config.context_builder = ->(data_import) {
-  { user: data_import.user, import_id: data_import.id }
-}
-```
-
-The returned object is available as `context` in all target instance methods.
-
-## Real-time progress
-
-DataPorter tracks import progress via JSON polling. The Stimulus progress controller polls `GET /imports/:id/status` every second and updates an animated progress bar.
-
-The status endpoint returns:
-
-```json
-{
-  "status": "importing",
-  "progress": { "current": 42, "total": 100, "percentage": 42 }
-}
-```
-
-No ActionCable or WebSocket configuration required -- it works out of the box with any deployment.
-
-## Auto-purge
-
-Old completed/failed imports can be cleaned up automatically:
-
-```bash
-# Run manually
-bin/rails data_porter:purge
-
-# Or schedule via cron (e.g. with whenever or solid_queue)
-# Removes imports older than purge_after (default: 60 days)
-```
-
-Attached files are purged from ActiveStorage along with the import record.

data/docs/MAPPING.md

@@ -1,44 +0,0 @@
-# Column Mapping
-
-For file-based sources (CSV/XLSX), DataPorter adds an interactive mapping step between upload and parsing. Users see their file's actual column headers and map each one to a target field via dropdowns.
-
-```
-File Header          Target Field
-+-----------+        +---------------+
-| Prenom    |   ->   | First Name  v |
-+-----------+        +---------------+
-+-----------+        +---------------+
-| Nom       |   ->   | Last Name   v |
-+-----------+        +---------------+
-```
-
-Dropdowns are pre-filled from the Target's `csv_mapping` when headers match. Users can adjust any mapping before continuing to the preview step.
-
-## Required fields
-
-Required target fields are marked with `*` in the dropdown labels. If any required field is left unmapped, a warning banner appears listing the missing fields. This validation is client-side only -- it warns but does not block submission.
-
-## Duplicate detection
-
-If two file headers are mapped to the same target field, the affected rows are highlighted with an orange border and a warning message appears. This helps catch accidental duplicate mappings before parsing.
-
-## Mapping Templates
-
-Mappings can be saved as reusable templates. When starting a new import, users select a saved template from a dropdown to auto-fill all column mappings at once. Templates are stored per-target, so each import type has its own template library.
-
-### Managing templates
-
-- **Inline**: Check "Save as template" in the mapping form and give it a name
-- **CRUD**: Use the "Mapping Templates" link on the imports index page to create, edit, and delete templates
-
-When a template is loaded, the "Save as template" checkbox is hidden since the user is already working from an existing template.
-
-## Mapping Priority
-
-When parsing, mappings are resolved in priority order:
-
-1. **User mapping** -- from the mapping UI (`config["column_mapping"]`)
-2. **Code mapping** -- from the Target DSL (`csv_mapping`)
-3. **Auto-map** -- parameterize headers to match column names
-
-Non-file sources (JSON, API) skip the mapping step entirely.

data/docs/ROADMAP.md

@@ -1,199 +0,0 @@
-# Roadmap
-
-## v1.0 — Production-ready DONE
-
-The goal is a gem that handles real-world imports reliably at scale.
-
-### ~~1. Records pagination~~ DONE
-
-Implemented in v0.6.0. Preview and completed pages are paginated (50 per page).
-Controller limits records loaded via `RecordPagination` concern.
-
-### ~~2. Import params~~ DONE
-
-Implemented in v0.9.0. Targets declare `params` with a DSL (`:select`, `:text`,
-`:number`, `:hidden`). Values stored in `config["import_params"]`, accessible
-via `import_params` in all target instance methods. See [Targets docs](TARGETS.md#params--).
-
-### ~~3. Security audit~~ DONE
-
-- Replaced `permit!` on import params and column mapping with whitelists
-- File size validation (`config.max_file_size`, default 10 MB)
-- MIME type validation per source type
-- XSS fix in template form controller (safe DOM methods)
-
-### ~~4. Safety guards~~ DONE
-
-- Max records guard (`config.max_records`, default 10,000)
-- Transaction mode (`config.transaction_mode`: `:per_record` or `:all`)
-- Fallback headers (auto-generate `col_1, col_2...` for empty header rows)
-
-### ~~5. Reject rows export~~ DONE
-
-Download CSV of failed/errored records with original data + error messages.
-Zero-dependency streaming via `send_data`.
-
-### ~~6. E2E integration tests~~ DONE
-
-6 end-to-end specs covering all source types (CSV, XLSX, JSON, API),
-import params flow, and reject rows CSV export. 395 specs total.
-
----
-
-## v1.1 — Deploy-ready
-
-Priority: features required to deploy DataPorter to real users.
-
-### Scoped imports
-
-Wire up `config.scope` so each user only sees their own imports. The
-configuration hook already exists but isn't connected to the controller query:
-
-```ruby
-DataPorter.configure do |config|
-  config.scope = ->(user) { { user_type: user.class.name, user_id: user.id } }
-end
-```
-
-The controller `index` and `show` actions apply the scope automatically.
-Combined with `parent_controller` inheriting from an authenticated controller,
-this enables full multi-tenant isolation — suitable for both B2B (tenant per
-organization) and B2C (user-level) scenarios.
-
-### Preview ↔ Mapping navigation
-
-Allow users to go back from preview to the mapping step and adjust column
-mapping without restarting the import. Currently the flow is one-way:
-mapping → parse → preview. Adding a "Back to mapping" button on the preview
-page would let users correct mapping mistakes after seeing the parsed data.
-
-### ~~CSV auto-detect: delimiter & encoding~~ DONE
-
-Implemented in v1.0.1. Auto-detect CSV delimiter (`,` `;` `\t`) via frequency
-analysis on the first line. Auto-detect file encoding: strip UTF-8 BOM, validate
-UTF-8, fallback to ISO-8859-1 transcoding. Explicit `col_sep` config takes
-precedence.
-
-### Column mapping for JSON and API sources
-
-The interactive column mapping step currently only works for file-based sources
-(CSV, XLSX). JSON and API sources have stable, predictable keys that rarely need
-remapping, but supporting mapping for all sources would provide a consistent UX.
-
----
-
-## v1.2 — Smart imports
-
-### Dry-run performance estimate
-
-After a dry run, display an estimated import time based on average record
-processing speed: "Estimated import time: ~2m30s". Helps users decide whether
-to launch the import now or schedule it for off-peak hours.
-
-### Permissions / RBAC
-
-Role-based access control for import operations. Allow host apps to restrict
-who can create imports, confirm imports, or access specific targets. Integrate
-with existing authorization frameworks (Pundit, CanCanCan) via a configurable
-policy hook.
-
-### Column transformers
-
-Built-in transformation pipeline applied per-column before the target's
-`transform` method. Declarative DSL in the target:
-
-```ruby
-columns do
-  column :email, type: :email, transform: [:strip, :downcase]
-  column :phone, type: :string, transform: [:strip, :normalize_phone]
-  column :born_on, type: :date, transform: [:parse_date]
-end
-```
-
-Ships with common transformers (`strip`, `downcase`, `titleize`,
-`normalize_phone`, `parse_date`). Custom transformers via a registry.
-
-### Auto-map heuristics
-
-Smart column mapping suggestions using tokenized header matching and synonym
-dictionaries. When a CSV has "E-mail Address", auto-suggest mapping to `:email`.
-Built-in synonyms for common patterns (phone → phone_number,
-first name → first_name). Configurable synonym lists per target.
-
----
-
-## v2.0 — Scale & Automation
-
-### Bulk import
-
-High-volume import support using `insert_all` / `upsert_all` for batch
-persistence. Bypass per-record `persist` calls when the target opts in,
-enabling 10-100x throughput for simple create/upsert scenarios. Configurable
-batch size, with fallback to per-record mode on conflict.
-
-### Update & diff mode
-
-Support update (upsert) imports alongside create-only. Given a
-`deduplicate_by` key, detect existing records and show a diff preview:
-new records, changed fields (highlighted), unchanged rows. User confirms
-which changes to apply. Enables recurring data sync workflows.
-
-### Resume / retry on failure
-
-If an import fails mid-way (timeout, crash, transient error), resume from
-the last successful record instead of restarting from scratch. Track a
-checkpoint index in the report. Critical for large imports (5k+ records)
-where re-processing everything is not acceptable.
-
-### API pagination
-
-Support paginated API sources. The current API source does a single GET,
-which works for small datasets but not for APIs returning thousands of
-records across multiple pages. Support offset, cursor, and link-header
-pagination strategies via `api_config`:
-
-```ruby
-api_config do
-  endpoint "https://api.example.com/contacts"
-  pagination :cursor, param: "after", root: "data", next_key: "meta.next_cursor"
-end
-```
-
-### Scheduled imports
-
-Recurring imports from API or remote sources on a cron schedule. A target
-declares a schedule, and DataPorter automatically fetches and imports at
-the configured interval. Built on ActiveJob with configurable queue.
-
----
-
-## v3.0 — Platform
-
-### Webhooks
-
-HTTP callbacks on import lifecycle events (started, completed, failed).
-Configurable per-target with URL, headers, and payload template. Enables
-integration with Slack notifications, CI pipelines, or external dashboards.
-
-### External connectors
-
-Source plugins beyond local files and HTTP APIs:
-
-- **Google Sheets** — OAuth2 + Sheets API, treat a spreadsheet as a source
-- **SFTP** — Poll a remote directory for new files
-- **AWS S3** — Watch a bucket/prefix for uploads
-- **Remote HTTP polling** — Periodically fetch from a paginated API
-
-Each connector implements the `Sources::Base` interface. Installed as
-optional companion gems (`data_porter-google_sheets`, `data_porter-s3`).
-
-### i18n
-
-Full internationalization of all UI strings, error messages, and status
-labels. Ship with English and French translations. Host apps can override
-or add languages via standard Rails I18n.
-
-### Dashboard & analytics
-
-Import statistics dashboard: success rates, average duration, records per
-import, most-used targets, failure trends. Mountable as an admin-only route.

data/docs/SOURCES.md

@@ -1,94 +0,0 @@
-# Sources
-
-DataPorter supports four source types. Each source reads data from a different format and feeds it through the same parsing pipeline.
-
-## CSV
-
-Upload a CSV file. Headers are extracted automatically and presented in the [column mapping](MAPPING.md) step. Configure header mappings with `csv_mapping` in your [Target](TARGETS.md) when file headers don't match your column names.
-
-Custom separator:
-
-```ruby
-import.config = { "separator" => ";" }
-```
-
-## XLSX
-
-Upload an Excel `.xlsx` file. Uses the same `csv_mapping` for header-to-column mapping as CSV. By default the first sheet is parsed; select a different sheet via config:
-
-```ruby
-import.config = { "sheet_index" => 1 }
-```
-
-Powered by [creek](https://github.com/pythonicrubyist/creek) for streaming, memory-efficient parsing.
-
-## JSON
-
-Upload a JSON file. Use `json_root` in your Target to specify the path to the records array. Raw JSON arrays are supported without `json_root`.
-
-```ruby
-json_root "data.users"
-```
-
-Given `{ "data": { "users": [...] } }`, records are extracted from `data.users`.
-
-## API
-
-Fetch records from an external API endpoint. No file upload is needed -- the engine calls the API directly.
-
-### Basic usage
-
-```ruby
-api_config do
-  endpoint "https://api.example.com/data"
-  headers({ "Authorization" => "Bearer token" })
-  response_root "results"
-end
-```
-
-| Option | Type | Description |
-|---|---|---|
-| `endpoint` | String or Proc | URL to fetch records from |
-| `headers` | Hash or Proc | HTTP headers sent with the request |
-| `response_root` | String | Key in the JSON response containing the records array (omit for top-level arrays) |
-
-### Dynamic endpoints and headers
-
-Both `endpoint` and `headers` accept lambdas for runtime values. The endpoint lambda receives the import's `config` hash:
-
-```ruby
-api_config do
-  endpoint ->(params) { "https://api.example.com/events?page=#{params[:page]}" }
-  headers -> { { "Authorization" => "Bearer #{ENV['API_TOKEN']}" } }
-  response_root "data"
-end
-```
-
-### Full example
-
-```ruby
-class EventTarget < DataPorter::Target
-  label "Events"
-  model_name "Event"
-  sources :api
-
-  api_config do
-    endpoint "https://api.example.com/events"
-    headers -> { { "Authorization" => "Bearer #{ENV['EVENTS_API_KEY']}" } }
-    response_root "events"
-  end
-
-  columns do
-    column :name,     type: :string, required: true
-    column :date,     type: :date
-    column :venue,    type: :string
-    column :capacity, type: :integer
-  end
-
-  def persist(record, context:)
-    Event.create!(record.attributes)
-  end
-end
-```
-
-When a user creates an import with source type **API**, the engine skips file upload entirely, calls the configured endpoint, parses the JSON response, and feeds the records through the same preview/validate/import pipeline as file-based sources.

data/docs/TARGETS.md

@@ -1,332 +0,0 @@
-# Targets
-
-Targets are plain Ruby classes in `app/importers/` that inherit from `DataPorter::Target`. Each target defines one import type: its columns, sources, mappings, and persistence logic.
-
-## Generator
-
-```bash
-bin/rails generate data_porter:target ModelName column:type[:required] ... [--sources csv xlsx]
-```
-
-Examples:
-
-```bash
-bin/rails generate data_porter:target User email:string:required name:string age:integer --sources csv xlsx
-bin/rails generate data_porter:target Product name:string price:decimal --sources csv
-bin/rails generate data_porter:target Order order_number:string total:decimal
-```
-
-Column format: `name:type[:required]`
-
-Supported types: `string`, `integer`, `decimal`, `boolean`, `date`.
-
-The `--sources` option specifies which source types the target accepts (default: `csv`). The UI will only show these sources when the target is selected.
-
-## Class-level DSL
-
-```ruby
-class OrderTarget < DataPorter::Target
-  label "Orders"
-  model_name "Order"
-  icon "fas fa-shopping-cart"
-  sources :csv, :json, :api, :xlsx
-
-  columns do
-    column :order_number, type: :string, required: true
-    column :total,        type: :decimal
-    column :placed_at,    type: :date
-    column :active,       type: :boolean
-    column :quantity,     type: :integer
-  end
-
-  csv_mapping do
-    map "Order #" => :order_number
-    map "Total ($)" => :total
-  end
-
-  json_root "data.orders"
-
-  api_config do
-    endpoint "https://api.example.com/orders"
-    headers({ "Authorization" => "Bearer token" })
-    response_root "data.orders"
-  end
-
-  deduplicate_by :order_number
-
-  dry_run_enabled
-
-  params do
-    param :warehouse_id, type: :select, label: "Warehouse", required: true,
-          collection: -> { Warehouse.pluck(:name, :id) }
-    param :currency, type: :text, default: "USD"
-  end
-end
-```
-
-### `label(value)`
-
-Human-readable name shown in the UI.
-
-### `model_name(value)`
-
-The ActiveRecord model name this target imports into (for display purposes).
-
-### `icon(value)`
-
-CSS icon class (e.g. FontAwesome) shown in the UI.
-
-### `sources(*types)`
-
-Accepted source types: `:csv`, `:json`, `:api`, `:xlsx`.
-
-### `columns { ... }`
-
-Defines the expected columns for this import. Each column accepts:
-
-| Parameter | Type | Default | Description |
-|---|---|---|---|
-| `name` | Symbol | (required) | Column identifier |
-| `type` | Symbol | `:string` | One of `:string`, `:integer`, `:decimal`, `:boolean`, `:date` |
-| `required` | Boolean | `false` | Whether the column must have a value |
-| `label` | String | Humanized name | Display label in the preview |
-
-### `csv_mapping { ... }`
-
-Maps CSV/XLSX header names to column names when they don't match:
-
-```ruby
-csv_mapping do
-  map "First Name" => :first_name
-  map "E-mail" => :email
-end
-```
-
-### `json_root(path)`
-
-Dot-separated path to the array of records within a JSON document:
-
-```ruby
-json_root "data.users"
-```
-
-Given `{ "data": { "users": [...] } }`, records are extracted from `data.users`.
-
-### `api_config { ... }`
-
-See [Sources: API](SOURCES.md#api) for full documentation.
-
-### `deduplicate_by(*keys)`
-
-Skip records that share the same value(s) for the given column(s):
-
-```ruby
-deduplicate_by :email
-deduplicate_by :first_name, :last_name
-```
-
-### `dry_run_enabled`
-
-Enables dry run mode for this target. A "Dry Run" button appears in the preview step. Dry run executes the full import pipeline (transform, validate, persist) inside a rolled-back transaction, giving a validation report without modifying the database.
-
-### `params { ... }`
-
-Declares extra form fields shown when this target is selected in the import form. Values are stored in `config["import_params"]` and accessible via `import_params` in all instance methods.
-
-```ruby
-params do
-  param :hotel_id, type: :select, label: "Hotel", required: true,
-        collection: -> { Hotel.pluck(:name, :id) }
-  param :currency, type: :text, label: "Currency", default: "EUR"
-  param :batch_size, type: :number, label: "Batch Size", default: "100"
-  param :tenant_id, type: :hidden, default: "abc123"
-end
-```
-
-Each param accepts:
-
-| Parameter | Type | Default | Description |
-|---|---|---|---|
-| `name` | Symbol | (required) | Param identifier |
-| `type` | Symbol | `:text` | One of `:select`, `:text`, `:number`, `:hidden` |
-| `required` | Boolean | `false` | Validated on import creation, shown with `*` in the form |
-| `label` | String | Humanized name | Display label in the form |
-| `default` | String | `nil` | Pre-filled value in the form |
-| `collection` | Lambda or Array | `nil` | For `:select` type -- `[[label, value], ...]` |
-
-Collection accepts both a lambda and a plain array. Use a lambda for dynamic data (evaluated when the form loads, not at boot time):
-
-```ruby
-param :hotel_id, type: :select, collection: -> { Hotel.pluck(:name, :id) }
-param :status,   type: :select, collection: [%w[Active active], %w[Archived archived]]
-```
-
-## Instance Methods
-
-### `import_params`
-
-Returns a hash of the import params values set by the user in the form. Available in all instance methods (`persist`, `transform`, `validate`, `after_import`, `on_error`). Defaults to `{}` when no params are declared.
-
-```ruby
-def persist(record, context:)
-  Guest.create!(
-    record.attributes.merge(
-      hotel_id: import_params["hotel_id"],
-      currency: import_params["currency"]
-    )
-  )
-end
-```
-
-Override these in your target to customize behavior.
-
-### `transform(record)`
-
-Transform a record before validation. Must return the (modified) record.
-
-```ruby
-def transform(record)
-  record.attributes["email"] = record.attributes["email"]&.downcase
-  record
-end
-```
-
-### `validate(record)`
-
-Add custom validation errors to a record:
-
-```ruby
-def validate(record)
-  record.add_error("Email is invalid") unless record.attributes["email"]&.include?("@")
-end
-```
-
-### `persist(record, context:)`
-
-**Required.** Save the record to your database. Raises `NotImplementedError` if not overridden.
-
-```ruby
-def persist(record, context:)
-  User.create!(record.attributes)
-end
-```
-
-### `after_import(results, context:)`
-
-Called once after all records have been processed:
-
-```ruby
-def after_import(results, context:)
-  AdminMailer.import_complete(context.user, results).deliver_later
-end
-```
-
-### `on_error(record, error, context:)`
-
-Called when a record fails to import:
-
-```ruby
-def on_error(record, error, context:)
-  Sentry.capture_exception(error, extra: { record: record.attributes })
-end
-```
-
-## Full example
-
-A complete target using most DSL features: multiple sources, import params, JSON root, API config, transform, custom validation, and lifecycle hooks.
-
-```ruby
-# frozen_string_literal: true
-
-class ContactTarget < DataPorter::Target
-  label "Contacts"
-  model_name "Contact"
-  icon "fas fa-address-book"
-  sources :csv, :xlsx, :json, :api
-  dry_run_enabled
-
-  columns do
-    column :name, type: :string, required: true
-    column :email, type: :email
-    column :phone_number, type: :string
-    column :address, type: :string
-    column :room, type: :string
-  end
-
-  params do
-    param :default_room, type: :text, label: "Default room"
-    param :import_source, type: :select, label: "Import source",
-          collection: [%w[Manual manual], %w[Migration migration], ["Directory sync", "sync"]]
-  end
-
-  json_root "contacts"
-
-  api_config do
-    endpoint "http://localhost:3001/contacts"
-    headers({ "Authorization" => "Bearer token" })
-    response_root :contacts
-  end
-
-  def transform(record)
-    apply_default_room(record)
-    normalize_phone(record)
-    record
-  end
-
-  def validate(record)
-    validate_email_format(record)
-  end
-
-  def persist(record, context:)
-    Contact.create!(record.attributes)
-  end
-
-  def after_import(results, context:)
-    Rails.logger.info("[DataPorter] Contacts: #{results[:created]} created, #{results[:errored]} errors")
-  end
-
-  def on_error(record, error, context:)
-    Rails.logger.warn("[DataPorter] Line #{record.line_number}: #{error.message}")
-  end
-
-  private
-
-  def apply_default_room(record)
-    return if record.data["room"].present?
-    return unless import_params["default_room"].present?
-
-    record.data["room"] = import_params["default_room"]
-  end
-
-  def normalize_phone(record)
-    phone = record.data["phone_number"]
-    return if phone.blank?
-
-    record.data["phone_number"] = phone.gsub(/\s/, "")
-  end
-
-  def validate_email_format(record)
-    email = record.data["email"]
-    return if email.blank?
-    return if email.match?(/\A[^@\s]+@[^@\s]+\z/)
-
-    record.add_error("Invalid email format: #{email}")
-  end
-end
-```
-
-This target exercises:
-
-| Feature | DSL / Hook | Effect |
-|---|---|---|
-| 4 sources | `sources :csv, :xlsx, :json, :api` | All source types available |
-| Typed columns | `type: :string, :email` | Built-in validation |
-| Required field | `required: true` on `name` | Rows without name get "missing" status |
-| Dry run | `dry_run_enabled` | Dry run button in preview |
-| Import params | `param :default_room`, `param :import_source` | Dynamic form fields |
-| JSON root | `json_root "contacts"` | Extracts from `{"contacts": [...]}` |
-| API config | `endpoint`, `headers`, `response_root` | Authenticated API fetch |
-| Transform | `apply_default_room`, `normalize_phone` | Fill blanks, strip whitespace |
-| Validate | `validate_email_format` | Custom error on invalid email |
-| After import | Logs summary | Post-import hook |
-| On error | Logs failed line | Per-record error hook |