Home Information - Your home, your data, organized.
Python
Paperless-ngx integration (ATTRIBUTE_REFERENCE capability) (#375)
Tony C40f932e0889b
diff --git a/docs/Integrations.md b/docs/Integrations.mdindex 0ffa6faf..a3679527 100644--- a/docs/Integrations.md+++ b/docs/Integrations.md@@ -14,8 +14,16 @@ enter it.## Enabling an integration+Most integrations are configured from the **Connectors** tab on the+Configure page. Paperless-ngx is configured from the **Content+Sources** tab instead, because it contributes searchable document+references rather than importing items — see its own page for the+walkthrough.++For a Connectors-tab integration:+1. In HI, click **CONFIGURE** at the bottom of the screen.-2. Select the **Integrations** tab.+2. Select the **Connectors** tab.3. Open the integrations picker:- If no integrations are configured yet, click **CONFIGUREINTEGRATIONS** in the main panel.@@ -39,6 +47,11 @@ enter it.- **[HomeBox](integrations/homebox.md)** — home inventory tracking.Imports HomeBox items as read-only HI items with custom fields andattached files (manuals, receipts, photos).+- **[Paperless-ngx](integrations/paperless-ngx.md)** — document+ management. Does not import items; instead lets you search+ paperless from inside HI and attach matching documents (warranty+ PDFs, manuals, receipts) as link references on items and+ Locations you already have.More integrations will be added as demand arises. The per-integrationpages each carry their own troubleshooting section that accretes@@ -46,8 +59,11 @@ real-world fixes over time — start there if something is not working.## Integrations vs. Data Import-Integrations on this page are live: HI mirrors the upstream system-continuously and changes flow in via the update action.+Most integrations on this page are live: HI mirrors the upstream+system continuously and changes flow in via the update action.+Paperless-ngx is a different shape — it contributes attachable+document references rather than importing items, and it talks to+paperless only when the operator opens the picker.A separate feature, [Data Import](DataImport.md), is a one-timecopy with no ongoing upstream link. Some integrations (HomeBoxdiff --git a/docs/dev/integrations/integration-guidelines.md b/docs/dev/integrations/integration-guidelines.mdindex 295eca35..fa5b2a2a 100644--- a/docs/dev/integrations/integration-guidelines.md+++ b/docs/dev/integrations/integration-guidelines.md@@ -10,12 +10,15 @@ Each integration is a Django app in `hi/services/` directory. The `hi.integratio- **detail_attrs**: Opaque data blob - only the integration uses this data### Capability model-Each integration declares its `IntegrationCapability` set on `IntegrationMetaData.capabilities` (`hi/integrations/enums.py`). Two capabilities exist today:+Each integration declares its `IntegrationCapability` set on `IntegrationMetaData.capabilities` (`hi/integrations/enums.py`). Three capabilities exist today:-- **`CONNECT`** — live mirror of an upstream system. Realized by an `IntegrationConnector` subclass returned from `IntegrationGateway.get_connector()`. All four production integrations (HA, ZM, Frigate, HomeBox) declare CONNECT.-- **`IMPORT`** — one-shot copy of upstream items into HI as locally-owned entities. Realized by an `IntegrationImporter` subclass returned from `IntegrationGateway.get_importer()`. HomeBox is the first integration to declare IMPORT alongside CONNECT (see [`docs/dev/integrations/data-import.md`](data-import.md) for the developer surface).+- **`CONNECT`** — live mirror of an upstream system. Realized by an `IntegrationConnector` subclass returned from `IntegrationGateway.get_connector()`. All four "Connectors"-tab integrations (HA, ZM, Frigate, HomeBox) declare CONNECT.+- **`IMPORT`** — one-shot copy of upstream items into HI as locally-owned entities. Realized by an `IntegrationImporter` subclass returned from `IntegrationGateway.get_importer()`. HomeBox is the only integration to declare IMPORT alongside CONNECT today (see [`docs/dev/integrations/data-import.md`](data-import.md) for the developer surface).+- **`ATTRIBUTE_REFERENCE`** — search-and-attach surface that contributes URL attributes to existing Entity / Location records (no entity import, no live mirror). Realized by an `IntegrationAttributeReferencer` subclass returned from `IntegrationGateway.get_attribute_referencer()`. Paperless-ngx is the only integration to declare ATTRIBUTE_REFERENCE today. ATTRIBUTE_REFERENCE-only integrations are configured on a sibling tab labeled "Content Sources" instead of "Connectors" — the page chrome differs because there's no monitor / sync lifecycle.-The two abstractions don't share a base class — commonality is composed through shared helpers (`hi/integrations/entity_operations.py`, `hi/integrations/placement_request.py`, etc.). The `connector/` and `importer/` sub-packages live as peers under `hi/integrations/`.+The three per-capability classes (`IntegrationConnector`, `IntegrationImporter`, `IntegrationAttributeReferencer`) share a common base `CapabilityGateway` (`hi/integrations/capability_gateway.py`). Each declares a `capability` class attribute identifying the `IntegrationCapability` it realizes, and overrides cross-capability concerns: `get_metadata()` (abstract), `get_description()` (operator-facing one-line description), and `get_attribute_actions_template_name()` (optional template fragment for the attribute form's action bar). Capability-specific concerns (sync, import, search) stay on the subclass. Adding a new capability means subclassing `CapabilityGateway`, declaring the `capability` class attribute, and overriding only the methods that apply to the new shape.++The `connector/`, `importer/`, and `referencer/` sub-packages live as peers under `hi/integrations/`.Per-attribute `IntegrationAttributeType` declarations may carry an optional `capabilities` set to restrict which capability's UI surfaces the attribute. Default is `ALL_CAPABILITIES`.@@ -79,7 +82,9 @@ Each integration is a self-contained Django app under `hi/services/<integration_- `monitors.py` — `PeriodicMonitor` subclass(es) for polling and health probes- `apps.py`, `urls.py`, `views.py` — standard Django wiring-`<prefix>` is a short integration mnemonic (`hass_`, `zm_`, `hb_`). Keep it consistent across all files within the integration.+`<prefix>` is a short integration mnemonic (`hass_`, `zm_`, `hb_`, `pl_`). Keep it consistent across all files within the integration.++ATTRIBUTE_REFERENCE-only integrations (paperless-ngx today) don't need all the role-files above — they have no monitors, no sync, no converter, and no manager singleton (the capability has no live state to own). They still ship `integration.py`, `<prefix>_metadata.py`, `<prefix>_client.py`, plus a `<prefix>_referencer.py` for the `IntegrationAttributeReferencer` subclass and `<prefix>_models.py` (or `_constants.py`) for the wire-format strings.### Centralize wire-format stringsEvery integration centralizes its wire-format strings — domain/endpoint names, attribute keys, device-class names, service names, special-state sentinels — in a single class per integration. The exemplar is `HassApi` in `hi/services/hass/hass_models.py`; ZoneMinder's equivalent is `hi/services/zoneminder/constants.py`. The converter, sync, controller, and service composer all import their wire strings from this single source.@@ -113,17 +118,24 @@ cd src/hi/services- Set fully qualified name in `apps.py`: `name = 'hi.services.myintegration'`- Add to `INSTALLED_APPS` in `hi/settings/base.py`-### 3. Define Integration Type-Add to `IntegrationType` enum in appropriate enums file+### 3. Declare Metadata and Capabilities+Create a module-level `IntegrationMetaData` instance (in `<prefix>_metadata.py`) declaring the integration's `integration_id`, label, logo path, attribute-type enum, and `capabilities` set. The `capabilities` set is what binds the integration to its UI surfaces — CONNECT puts it on the Connectors tab; IMPORT adds it to the Data Import tab; ATTRIBUTE_REFERENCE puts it on the Content Sources tab.### 4. Create Gateway Class-Implement `IntegrationGateway` with required methods:-- `activate(integration_instance)` - Setup and validation-- `deactivate(integration_instance)` - Cleanup and shutdown-- `manage(request, integration_instance)` - Management interface+Implement `IntegrationGateway` (in `integration.py`) with the methods that apply to the declared capabilities:++- `get_metadata()` — return the `IntegrationMetaData` instance. Required.+- `get_connector()` — return an `IntegrationConnector` subclass instance when CONNECT is advertised; default `None`.+- `get_importer()` — return an `IntegrationImporter` subclass instance when IMPORT is advertised; default `None`.+- `get_attribute_referencer()` — return an `IntegrationAttributeReferencer` subclass instance when ATTRIBUTE_REFERENCE is advertised; default `None`.+- `validate_configuration(integration_attributes)` — schema-only validation of the attribute set. Required (no network operations).+- `validate_access(integration_attributes, timeout_secs)` — bounded live probe against the configured credentials. Required (used by the configure flow and by health-check helpers).+- `notify_settings_changed()` — invoked by the framework after the operator saves attributes. Reload your manager / re-init clients here. Default no-op.-### 5. Register with Factory-Add gateway mapping in `hi/integrations/integration_factory.py`+The per-capability work (sync, candidate-listing, search) lives on the capability subclass returned from the matching `get_*` method.++### 5. Auto-Discovery+No factory registration is needed. `IntegrationManager.discover_defined_integrations()` walks `INSTALLED_APPS` for `hi.services.*` apps, imports each app's `integration.py`, and registers any `IntegrationGateway` subclass it finds. As long as the app is in `INSTALLED_APPS` and `integration.py` exposes a gateway subclass, it shows up automatically.### 6. Write Per-Integration DocumentationEvery user-configured integration MUST ship with two short docs based@@ -152,15 +164,13 @@ the user-facing landing page at [`docs/Integrations.md`](../../Integrations.md).## Gateway Implementation Patterns### Gateway Methods-**activate()**: Validate config, validate access, initialize resources-**deactivate()**: Clean up entities, close connections, update status-**manage()**: Handle POST actions (sync, test, config), render management UI+See "4. Create Gateway Class" above for the full method list. Highlights:++- **`validate_configuration(attrs)`** — schema check only. Returns `IntegrationValidationResult`. Must not perform network operations.+- **`validate_access(attrs, timeout_secs)`** — live probe against the proposed credentials. Returns `ConnectionTestResult`. Must respect the timeout. Used at attribute-save time and before relaunching monitors on Resume.+- **`get_<capability>()`** — return the capability instance the framework consults for capability-specific work. Returning `None` opts the integration out of that capability's UI surfaces even if the capability is in `IntegrationMetaData.capabilities` (defensive disable).-### Return Format-All gateway methods return dict with:-- `status`: 'success' or 'error'-- `message`: User-friendly status message-- `redirect`: Optional redirect URL+The framework owns the surrounding workflow (configure modal, save lifecycle, sync UI, picker UI). The gateway and its capability instances supply the integration-specific bits.## Integration Patterns@@ -175,27 +185,29 @@ All gateway methods return dict with:- **Cleanup**: Remove entities no longer in external system### Error Handling-Custom exception hierarchy:-- `IntegrationError` - Base class-- `ConnectionError` - Network/connectivity issues-- `AuthenticationError` - Auth/authorization failures-- `DataValidationError` - Invalid data from external source+Custom exception hierarchy (`hi/integrations/exceptions.py`):+- `IntegrationError` — base class.+- `IntegrationDisabledError` — operation attempted against a disabled integration.+- `IntegrationAttributeError` — required attribute missing or invalid.+- `IntegrationConnectionError` — upstream unreachable / auth rejected during a live operation.## Key Base Classes & Modules### Core Classes-- `hi.integration.integration_gateway.IntegrationGateway` - Base gateway class-- `hi.utils.singleton.Singleton` - Singleton pattern for gateways-- `hi.integrations.enums.IntegrationStatus` - Status enumeration--### Factory Pattern-- `hi.integrations.integration_factory.py` - Gateway registration-- `hi.integrations.exceptions.py` - Custom exception classes+- `hi.integrations.integration_gateway.IntegrationGateway` — per-integration entry point; auto-discovered from each `hi.services.*` app's `integration.py`.+- `hi.integrations.capability_gateway.CapabilityGateway` — shared base of the three per-capability classes; carries `capability`, `get_metadata`, `get_description`, `get_attribute_actions_template_name`.+- `hi.integrations.connector.integration_connector.IntegrationConnector` — CONNECT capability surface (sync, monitor, controller, health).+- `hi.integrations.importer.integration_importer.IntegrationImporter` — IMPORT capability surface (candidate list, run, discard).+- `hi.integrations.referencer.integration_referencer.IntegrationAttributeReferencer` — ATTRIBUTE_REFERENCE capability surface (search).+- `hi.integrations.integration_manager.IntegrationManager` — discovery and lifecycle singleton.+- `hi.apps.common.singleton.Singleton` — singleton base used by `IntegrationManager` and many per-integration managers.### Example Integrations-- `hi.services.hass/` - Home Assistant integration-- `hi.services.zoneminder/` - ZoneMinder integration-- `hi.services.homebox/` - HomeBox integration+- `hi.services.hass/` — Home Assistant (CONNECT).+- `hi.services.zoneminder/` — ZoneMinder (CONNECT).+- `hi.services.frigate/` — Frigate (CONNECT).+- `hi.services.homebox/` — HomeBox (CONNECT + IMPORT).+- `hi.services.paperless/` — paperless-ngx (ATTRIBUTE_REFERENCE-only). Slimmer file layout — no manager singleton, no monitors, no converter — because the capability has no live state to own.## Related Documentation- [Service Patterns](service-patterns.md)diff --git a/docs/dev/integrations/paperless-ngx.md b/docs/dev/integrations/paperless-ngx.mdnew file mode 100644index 00000000..6c917873--- /dev/null+++ b/docs/dev/integrations/paperless-ngx.md@@ -0,0 +1,56 @@+# Paperless-ngx++## Capability shape++Paperless declares only the `ATTRIBUTE_REFERENCE` capability — no+connector, no importer, no manager singleton, no monitors. The+gateway returns a referencer, and the referencer translates+paperless's documents-search response into `AttributeReferenceResult`+rows. Per-search HTTP happens inline; there is no cached client.++## Key design decisions++- **Thumbnail proxy, not URL passthrough**. The picker embeds+ `<img src=…>` inside HI, so the browser cannot supply the+ paperless API token. The referencer emits HI's proxy URL as+ `thumbnail_url`, and the proxy view fetches upstream with the+ configured token. Same problem HomeBox solves with+ `homebox_attachment_proxy`.+- **Source URL is NOT proxied**. The persisted `source_url` is+ paperless's own per-document web URL. Operators authenticate with+ paperless's own session when they click — same UX as cut-and-paste.+ Proxying would couple the link's lifetime to HI's session.+- **No manager singleton**. ATTRIBUTE_REFERENCE has no monitors and+ no cached state, so there is no `pl_manager.py`. The client is+ built per-call from the stored attributes; `build_client` is the+ entry point to refactor through if a reason to cache emerges.+- **Snippet extraction client-side**. Paperless's search endpoint+ returns full document `content` per hit, not pre-built excerpts.+ The referencer extracts a short window around the matched query,+ falling back to a leading window when the query does not match+ verbatim (e.g., paperless matched on a stemmed form).+- **Single deployment**. The framework discovers one paperless+ integration per app directory. Multiple paperless instances are+ not supported; if that ever matters, the gateway's metadata id+ and the proxy URL would both need to become per-instance.++## Upstream surfaces touched++Wire-format strings live in `pl_models.py`; the integration touches+three paperless endpoints — the documents-search API, the per-document+thumbnail API (streamed through HI's proxy view), and the per-document+web URL (persisted unchanged as `source_url`). Auth is+`Authorization: Token <value>` on every upstream call.++## Testing++Tests live in `src/hi/services/paperless/tests/` and mock all upstream+HTTP. For end-to-end exercise without a real paperless install, use+the simulator at `src/hi/simulator/services/paperless/` — it supports+parametric response shapes (result count, mime mix, thumbnails on/off,+snippets on/off, artificial latency).++## References++- Upstream API: <https://docs.paperless-ngx.com/api/>+- Capability framework: [Integration Guidelines](integration-guidelines.md)diff --git a/docs/integrations/paperless-ngx.md b/docs/integrations/paperless-ngx.mdnew file mode 100644index 00000000..d93e62ab--- /dev/null+++ b/docs/integrations/paperless-ngx.md@@ -0,0 +1,118 @@+<img src="../../src/hi/static/img/hi-logo-w-tagline-197x96.png" alt="Home Information Logo" width="128">++# Paperless-ngx++## Overview++This integration lets **Home Information (HI)** search a+**paperless-ngx (paperless)** server and attach documents from it as+references on existing HI items and Locations. Unlike the other+integrations on the integrations page, paperless does not import any+items into HI — it contributes searchable references that get saved+as link attributes (title + URL) on items you already have. Typical+use case: link a dishwasher's warranty PDF, a thermostat's manual,+or a property's deed to the matching HI item or Location.++## Prerequisites++- A reachable paperless-ngx server (1.x or 2.x). The HI server must+ be able to reach paperless over HTTP or HTTPS at the URL you will+ configure; cross-origin browser fetches are not used, so reverse+ proxies are fine as long as the HI server can reach the address.+- A paperless user account with an API token. The token's user+ determines which documents the integration can see — give it a+ user that has the document-list permissions you want exposed+ through HI.++## Obtaining credentials++1. Sign in to paperless as the user whose document visibility you+ want to expose through HI.+2. Open the user's profile page (top-right user menu in the+ paperless web UI).+3. Click **Create token** (or **Regenerate token** if one already+ exists). Copy the generated token.+4. Keep paperless's per-user / per-group permissions in mind — the+ token sees only what its user can see.++## Configuration values++| Field | What to enter | Notes |+|-------|---------------|-------|+| API URL | Base URL of your paperless server, e.g. `https://paperless.example.com/` | Either form works (trailing slash optional). Use the same scheme + host you use in the browser. The integration appends `/api/documents/` and other paths internally. |+| API Token | The token copied from paperless's user profile | Sent as `Authorization: Token <value>` on every upstream call. Treated as a secret. |++## Setup walkthrough++Paperless is configured from the **Content Sources** tab on the+Configure page (it is not on the Connectors tab — see+[Integrations](../Integrations.md) for the distinction).++1. In HI, click **CONFIGURE** at the bottom of the screen.+2. Select the **Content Sources** tab.+3. Choose **Paperless-ngx** and fill in the two configuration values+ above. **Test Connection** issues a small probe against your+ paperless server and reports back; **Save** records the values.++Once paperless is configured, use it from any item or Location edit+page:++1. Click **Link Content** in the action bar to open the picker.+2. Type a query, tick the documents you want, and click **Add+ Links** (the button shows the running count, e.g. "Add 3 Links").++Each selection becomes a new attribute on the item — the attribute's+name is the document title and its value is the per-document URL on+your paperless server. Clicking the saved link later takes you to+paperless directly (you authenticate with paperless's own session).++## Troubleshooting++### Test Connection fails with "Paperless auth rejected"++The token was rejected (HTTP 401 or 403). Verify the token in+paperless's user profile and re-paste it. Tokens are sensitive to+leading/trailing whitespace.++### Test Connection fails with "Paperless unreachable"++The HI server cannot reach the configured URL. Check the scheme+(`http` vs. `https`), hostname, and port; from a shell on the HI+server, try `curl -I <API URL>` to confirm reachability.++### Picker returns no results++Confirm the query against paperless's own search UI as the same user+whose token you configured. If paperless's search returns nothing+for the same query, the token's user lacks visibility into the+documents you expect. If paperless's UI returns results but the+picker does not, increase the per-page count in the picker.++### Thumbnails do not load in the picker++Thumbnails are fetched through HI so the browser does not need a+paperless session. If thumbnails appear broken, check the HI logs+for `Paperless thumb proxy` warnings — the upstream URL or token+is likely misconfigured. The picker still works without thumbnails;+the fallback icon is used.++### Saved links open paperless's login page++The saved link points to paperless's per-document URL; clicking it+takes you to paperless directly, not through HI. You authenticate+with paperless's own session. If you are not signed in to paperless+when you click, paperless will prompt you.++## Known limitations++- Saved attribute links point to your paperless server's URL. If you+ later disable or reconfigure paperless (different host), those+ saved links will not automatically follow.+- There is no continuous sync. The integration only fetches when an+ operator opens the picker and searches. No background polling, no+ monitor health UI.+- The integration does not create HI items of its own. Documents are+ only attachable to items / Locations that already exist in HI.+- Search uses paperless's own full-text engine; ranking and matching+ semantics are whatever paperless provides. The picker preserves+ paperless's ordering.diff --git a/src/hi/apps/attribute/templatetags/attribute_extras.py b/src/hi/apps/attribute/templatetags/attribute_extras.pyindex cad883a0..497af1e1 100644--- a/src/hi/apps/attribute/templatetags/attribute_extras.py+++ b/src/hi/apps/attribute/templatetags/attribute_extras.py@@ -1,24 +1,29 @@import re+from urllib.parse import urlparsefrom django import template-from django.core.exceptions import ValidationError-from django.core.validators import URLValidatorfrom django.utils.html import escape, format_htmlfrom django.utils.safestring import mark_saferegister = template.Library()-_url_validator = URLValidator()_URL_IN_TEXT_PATTERN = re.compile(r'https?://[^\s<>"\']+')_TRAILING_PUNCTUATION = '.,;:!?)]}'def _is_valid_url(value):- """Return True when value passes Django URL validation."""+ """Return True when value looks like an http(s) URL with a host.++ Single-label intranet hostnames (e.g. ``http://cassandra:4100/…``)+ are accepted; Django's URLValidator rejects those because they+ lack a TLD, but they're common on LANs.+ """try:- _url_validator(value)- except ValidationError:+ parsed = urlparse(value)+ except ValueError:+ return False+ if parsed.scheme not in ('http', 'https'):return False- return True+ return bool(parsed.netloc)def _split_url_and_trailing_punctuation(candidate):diff --git a/src/hi/apps/attribute/tests/test_templatetags.py b/src/hi/apps/attribute/tests/test_templatetags.pyindex 7f7f5a1f..1e56d460 100644--- a/src/hi/apps/attribute/tests/test_templatetags.py+++ b/src/hi/apps/attribute/tests/test_templatetags.py@@ -185,8 +185,8 @@ class TestAttributeTextUrlFilters(TestCase):def test_attribute_text_has_url_detects_url_with_wrapping_punctuation(self):self.assertTrue(attribute_text_has_url("Open this (https://example.com/docs)."))- def test_attribute_text_has_url_ignores_invalid_http_candidates(self):- self.assertFalse(attribute_text_has_url("Broken candidate: https://bad"))+ def test_attribute_text_has_url_accepts_single_label_intranet_host(self):+ self.assertTrue(attribute_text_has_url("Internal: http://cassandra:4100/documents/8/details/"))def test_attribute_text_linkify_renders_multiple_links_inline(self):rendered = attribute_text_linkify(@@ -217,9 +217,15 @@ class TestAttributeTextUrlFilters(TestCase):rendered,)- def test_attribute_text_linkify_does_not_link_invalid_candidates(self):- rendered = attribute_text_linkify('Broken: https://bad and valid: https://example.com')- self.assertIn('Broken: https://bad', rendered)+ def test_attribute_text_linkify_links_single_label_intranet_host(self):+ rendered = attribute_text_linkify(+ 'Intranet: http://cassandra:4100/documents/8/details/ and public: https://example.com'+ )+ self.assertIn(+ '<a href="http://cassandra:4100/documents/8/details/" target="_blank" rel="noopener noreferrer">'+ 'http://cassandra:4100/documents/8/details/</a>',+ rendered,+ )self.assertIn('<a href="https://example.com" target="_blank" rel="noopener noreferrer">https://example.com</a>',rendered,diff --git a/src/hi/apps/common/templatetags/icons.py b/src/hi/apps/common/templatetags/icons.pyindex a9ac3342..f4f27e04 100644--- a/src/hi/apps/common/templatetags/icons.py+++ b/src/hi/apps/common/templatetags/icons.py@@ -48,6 +48,7 @@ AVAILABLE_ICONS = {'info-circle','layers','lightbulb',+ 'link','lock','map-pin','minus-circle',diff --git a/src/hi/apps/config/enums.py b/src/hi/apps/config/enums.pyindex 393edd55..f893b657 100644--- a/src/hi/apps/config/enums.py+++ b/src/hi/apps/config/enums.py@@ -16,11 +16,12 @@ class ConfigPageType(LabeledEnum):self.url_name = url_namereturn- SETTINGS = ('Settings' , '' , 'config_settings' )- INTEGRATIONS_CONNECT = ('Integrations' , '' , 'integrations_connect_home' )- EVENTS = ('Triggers' , '' , 'event_definitions' )- INTEGRATIONS_IMPORT = ('Data Import' , '' , 'integrations_import_home' )- SYSTEM_INFO = ('System Info' , '' , 'system_info' )+ SETTINGS = ('Settings' , '' , 'config_settings' )+ EVENTS = ('Triggers' , '' , 'event_definitions' )+ INTEGRATIONS_CONNECT = ('Connectors' , '' , 'integrations_connect_home' )+ INTEGRATIONS_REFERENCE = ('Content Sources' , '' , 'integrations_reference_home' )+ INTEGRATIONS_IMPORT = ('Data Import' , '' , 'integrations_import_home' )+ SYSTEM_INFO = ('System Info' , '' , 'system_info' )@classmethoddef default(cls):diff --git a/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html b/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.htmlindex cf7d69ae..b50c6aa6 100644--- a/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html+++ b/src/hi/apps/entity/templates/entity/panes/entity_edit_content_body.html@@ -1,9 +1,22 @@{% extends "attribute/components/edit_content_body.html" %}+{% load icons %}+{% load integration_tags %}{% comment %}Entity V2 Content Body FragmentExtends the generic attribute edit content body with entity-specific field layout.{% endcomment %}+{% block additional_actions %}+{% has_attribute_referencers as has_referencers %}+{% if has_referencers and attr_page_context.allow_internal_attributes %}+<a href="{% url 'integrations_attribute_reference_picker' %}?item_type=ENTITY&item_id={{ attr_item_context.owner.id }}"+ data-async="modal"+ class="btn btn-sm btn-outline-primary mb-0">+ {% icon "link" size="sm" css_class="hi-icon-left" %}Link Content+</a>+{% endif %}+{% endblock %}+{% block owner_fields %}<!-- Entity-specific fields: Name and Type fields for modal editing --><div class="row">@@ -44,4 +57,4 @@ Extends the generic attribute edit content body with entity-specific field layou</div></div></div>-{% endblock %}\ No newline at end of file+{% endblock %}diff --git a/src/hi/apps/location/templates/location/panes/location_edit_content_body.html b/src/hi/apps/location/templates/location/panes/location_edit_content_body.htmlindex ff7b5550..0773788d 100644--- a/src/hi/apps/location/templates/location/panes/location_edit_content_body.html+++ b/src/hi/apps/location/templates/location/panes/location_edit_content_body.html@@ -1,9 +1,22 @@{% extends "attribute/components/edit_content_body.html" %}+{% load icons %}+{% load integration_tags %}{% comment %}Location V2 Content Body FragmentExtends the generic attribute edit content body with location-specific field layout.{% endcomment %}+{% block additional_actions %}+{% has_attribute_referencers as has_referencers %}+{% if has_referencers and attr_page_context.allow_internal_attributes %}+<a href="{% url 'integrations_attribute_reference_picker' %}?item_type=LOCATION&item_id={{ attr_item_context.owner.id }}"+ data-async="modal"+ class="btn btn-sm btn-outline-primary mb-0">+ {% icon "link" size="sm" css_class="hi-icon-left" %}Link Content+</a>+{% endif %}+{% endblock %}+{% block owner_fields %}<!-- Location-specific fields: Only name field for modal editing --><div class="row">@@ -24,4 +37,4 @@ Extends the generic attribute edit content body with location-specific field lay</div></div></div>-{% endblock %}\ No newline at end of file+{% endblock %}diff --git a/src/hi/constants.py b/src/hi/constants.pyindex a97e9086..faa6b7b6 100644--- a/src/hi/constants.py+++ b/src/hi/constants.py@@ -161,6 +161,39 @@ DIVID = {# Entity Picker - Filter values'ENTITY_PICKER_FILTER_ALL': 'all',+ # ATTRIBUTE_REFERENCE picker — DOM classes / data attributes+ # / wire-format field names shared between the picker templates,+ # the picker views, and attr-picker.js. Mirror these in+ # ``src/hi/static/js/main.js`` (``Hi.ATTR_PICKER_*``).+ 'ATTR_PICKER_ROOT_CLASS': 'hi-attr-picker',+ 'ATTR_PICKER_CHIPS_CLASS': 'hi-attr-picker-chips',+ 'ATTR_PICKER_CHIPS_EMPTY_CLASS': 'hi-attr-picker-chips-empty',+ 'ATTR_PICKER_CHIP_REMOVE_CLASS': 'hi-attr-picker-chip-remove',+ 'ATTR_PICKER_RESULTS_CLASS': 'hi-attr-picker-results',+ 'ATTR_PICKER_SEARCH_FORM_CLASS': 'hi-attr-picker-search-form',+ 'ATTR_PICKER_ATTACH_FORM_CLASS': 'hi-attr-picker-attach-form',+ 'ATTR_PICKER_ATTACH_BTN_CLASS': 'hi-attr-picker-attach-btn',+ 'ATTR_PICKER_ATTACH_LABEL_CLASS': 'hi-attr-picker-attach-label',+ 'ATTR_PICKER_RESULT_CHECKBOX_CLASS': 'hi-attr-picker-result-checkbox',+ 'ATTR_PICKER_SEARCH_URL_ATTR': 'data-attr-picker-search-url',+ 'ATTR_PICKER_TITLE_ATTR': 'data-attr-picker-title',+ 'ATTR_PICKER_SOURCE_URL_ATTR': 'data-attr-picker-source-url',+ 'ATTR_PICKER_QUERY_FIELD': 'query',+ 'ATTR_PICKER_LIMIT_FIELD': 'limit',+ 'ATTR_PICKER_ITEM_TYPE_FIELD': 'item_type',+ 'ATTR_PICKER_ITEM_ID_FIELD': 'item_id',+ 'ATTR_PICKER_INTEGRATION_ID_FIELD': 'integration_id',+ 'ATTR_PICKER_SELECTIONS_JSON_FIELD': 'selections_json',+ 'ATTR_PICKER_SELECTION_TITLE_KEY': 'title',+ 'ATTR_PICKER_SELECTION_URL_KEY': 'source_url',+ 'ATTR_PICKER_SOURCE_BANNER_CLASS': 'hi-attr-picker-source-banner',+ 'ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS': 'hi-attr-picker-source-banner-logo',+ 'ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS': 'hi-attr-picker-source-banner-label',+ 'ATTR_PICKER_SOURCE_OPTION_CLASS': 'hi-attr-picker-source-option',+ 'ATTR_PICKER_SOURCE_ID_ATTR': 'data-attr-picker-source-id',+ 'ATTR_PICKER_SOURCE_LOGO_ATTR': 'data-attr-picker-source-logo',+ 'ATTR_PICKER_SOURCE_LABEL_ATTR': 'data-attr-picker-source-label',+# Location SVG Editor Grid Structure'LOCATION_SVG_EDIT_TOP': 'hi-location-svg-editor-top','LOCATION_SVG_EDIT_BOTTOM': 'hi-location-svg-editor-bottom',diff --git a/src/hi/integrations/capability_gateway.py b/src/hi/integrations/capability_gateway.pynew file mode 100644index 00000000..9a8ae3f2--- /dev/null+++ b/src/hi/integrations/capability_gateway.py@@ -0,0 +1,59 @@+"""Common base for the per-capability gateway peers.++``IntegrationConnector``, ``IntegrationImporter``, and+``IntegrationAttributeReferencer`` are the three per-capability+gateway classes today: each is the framework-facing surface for a+specific ``IntegrationCapability``. They are conceptually peers but+historically shared no base, leaving cross-capability concerns with+no natural home.++``CapabilityGateway`` is the shared base. Things that apply to *any*+capability (capability identification, operator-facing description,+attribute-form action extensions, etc.) live here. Things that are+genuinely capability-specific (sync, import, search) stay on the+subclass.++Adding a new capability means subclassing here, declaring the+``capability`` class attribute, and overriding only the methods that+make sense for the new shape.+"""+from typing import Optional++from .enums import IntegrationCapability+from .transient_models import IntegrationMetaData+++class CapabilityGateway:+ """Base for per-capability gateway peers."""++ # Subclasses declare which ``IntegrationCapability`` they+ # realize. The framework reads this when iterating an+ # integration's capability gateways uniformly.+ capability: IntegrationCapability++ def get_metadata(self) -> IntegrationMetaData:+ """Return the integration's ``IntegrationMetaData`` constant+ (the same object the integration's ``IntegrationGateway``+ exposes via ``get_metadata()``). The framework reads+ ``.integration_id`` and ``.label`` from it for shared+ operations like the auto-reconnect pre-pass and the+ entity-removal helper, so each subclass declares the source+ of truth in one place instead of repeating the values at+ every call site."""+ raise NotImplementedError('Subclasses must override this method')++ def get_description(self) -> Optional[str]:+ """One-line operator-facing description of what this+ capability does for this integration. Surfaces in+ capability-specific UI (Content Sources header, future+ per-source descriptions, etc.). Default None — UI omits the+ description when not provided."""+ return None++ def get_attribute_actions_template_name(self) -> Optional[str]:+ """Optional template fragment to render in the integration+ attribute form's action bar. Default None — the action bar+ shows only the framework's free buttons. Subclasses override+ to provide capability-specific actions (status badges,+ lifecycle buttons, etc.)."""+ return Nonediff --git a/src/hi/integrations/connector/integration_connector.py b/src/hi/integrations/connector/integration_connector.pyindex b13ad2c2..9c6c7673 100644--- a/src/hi/integrations/connector/integration_connector.py+++ b/src/hi/integrations/connector/integration_connector.py@@ -24,17 +24,19 @@ from hi.apps.monitor.periodic_monitor import PeriodicMonitorfrom hi.apps.sense.transient_models import SensorResponsefrom hi.apps.system.health_status_provider import HealthStatusProvider+from hi.integrations.capability_gateway import CapabilityGatewayfrom hi.integrations.entity_operations import EntityIntegrationOperations+from hi.integrations.enums import IntegrationCapabilityfrom .external_view_data import ExternalViewDatafrom .integration_controller import IntegrationControllerfrom .sync_check import IntegrationSyncCheck, SyncDeltafrom .sync_result import IntegrationSyncResult-from hi.integrations.transient_models import IntegrationKey, IntegrationMetaData+from hi.integrations.transient_models import IntegrationKeylogger = logging.getLogger(__name__)-class IntegrationConnector:+class IntegrationConnector( CapabilityGateway ):"""Base class for per-integration connectors.@@ -52,11 +54,13 @@ class IntegrationConnector:integration genuinely needs concurrent sync."""+ capability = IntegrationCapability.CONNECT+# Single shared lock name across all integration syncs. See class# docstring above for the rationale.SYNCHRONIZATION_LOCK_NAME = 'integrations_sync'- def get_description(self, is_initial_connect: bool) -> Optional[str]:+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:"""Optional copy describing what this integration's sync will do,surfaced to the operator in the framework's pre-sync@@ -106,6 +110,14 @@ class IntegrationConnector:availability."""raise NotImplementedError('Subclasses must override this method')+ def get_attribute_actions_template_name(self) -> Optional[str]:+ """Per-capability template fragment to render in the+ integration attribute form's action bar. CONNECT contributes+ the health-status badge that links to the health-detail+ modal. Individual integrations can override to substitute+ their own fragment."""+ return 'integrations/connector/panes/connect_attribute_actions.html'+def get_entity_video_stream(self, entity: Entity) -> Optional[VideoStream]:"""Return the live video stream for ``entity``, or ``None`` whenthe integration cannot produce one. Opt-in capability — most@@ -210,7 +222,7 @@ class IntegrationConnector:if result.error_list:returntry:- metadata = self.get_integration_metadata()+ metadata = self.get_metadata()except NotImplementedError:returntry:@@ -268,19 +280,9 @@ class IntegrationConnector:"""return None- def get_integration_metadata(self) -> IntegrationMetaData:- """- Subclasses return their integration's ``IntegrationMetaData``- constant (the same object the gateway exposes via- ``get_metadata()``). The framework reads ``.integration_id``- and ``.label`` from it for shared operations like the- auto-reconnect pre-pass and the entity-removal helper, so- each subclass declares the source of truth in one place- instead of repeating the values at every call site.- """- raise NotImplementedError(- f'{self.__class__.__name__} must override get_integration_metadata()'- )+ # ``get_metadata`` is inherited from CapabilityGateway. CONNECT+ # subclasses must implement it; the base raises NotImplementedError+ # via the inherited abstract.def reconnect_disconnected_items(self,@@ -332,7 +334,7 @@ class IntegrationConnector:if not unmatched_upstream_keys:return- metadata = self.get_integration_metadata()+ metadata = self.get_metadata()candidates = EntityIntegrationOperations.find_reconnect_candidates(integration_id = metadata.integration_id,upstream_keys = unmatched_upstream_keys,@@ -430,7 +432,7 @@ class IntegrationConnector:"""EntityIntegrationOperations.remove_entities_with_closure(seed_entity_ids = { entity.id },- integration_name = self.get_integration_metadata().label,+ integration_name = self.get_metadata().label,preserve_user_data = getattr( self, '_preserve_user_data', True ),result = result,)diff --git a/src/hi/integrations/connector/views.py b/src/hi/integrations/connector/views.pyindex b3152de8..abbdd90b 100644--- a/src/hi/integrations/connector/views.py+++ b/src/hi/integrations/connector/views.py@@ -124,7 +124,7 @@ class IntegrationPreSyncView( HiModalView, IntegrationViewMixin ):context = {'integration_data': integration_data,'is_initial_connect': is_initial_connect,- 'sync_description': connector.get_description(+ 'sync_description': connector.get_sync_description(is_initial_connect = is_initial_connect,),'sync_url': sync_url,@@ -179,6 +179,9 @@ class ConnectorConfigureView( CapabilityConfigureView, ConnectorViewMixin ):template_name = 'integrations/connector/modals/integration_enable.html'error_title = 'Cannot configure integration.'+ def get_capability_gateway( self, integration_data ):+ return integration_data.integration_gateway.get_connector()+def handle_post_success(self, request, integration_data):IntegrationManager().enable_integration(integration_data = integration_data,@@ -334,7 +337,7 @@ class ConnectorManageView( ConfigPageView, IntegrationViewMixin, AttributeEditViattr_item_context = IntegrationAttributeItemEditContext(integration_data = integration_data,- capability = IntegrationCapability.CONNECT,+ capability_gateway = integration_data.integration_gateway.get_connector(),health_status = health_status_provider.health_status,)integration_data_list = self.get_integration_data_list(@@ -406,7 +409,7 @@ class ConnectorManageView( ConfigPageView, IntegrationViewMixin, AttributeEditViattr_item_context = IntegrationAttributeItemEditContext(integration_data = integration_data,- capability = IntegrationCapability.CONNECT,+ capability_gateway = integration_data.integration_gateway.get_connector(),health_status = health_status_provider.health_status,)diff --git a/src/hi/integrations/enums.py b/src/hi/integrations/enums.pyindex b01103cb..e930823d 100644--- a/src/hi/integrations/enums.py+++ b/src/hi/integrations/enums.py@@ -8,6 +8,10 @@ class IntegrationCapability( LabeledEnum ):CONNECT = ( 'Connect', 'Live mirror of an upstream system.' )IMPORT = ( 'Import', 'One-shot pull of upstream items into HI.' )+ ATTRIBUTE_REFERENCE = (+ 'Attribute Reference',+ 'Search-and-attach external documents as Entity/Location attributes.',+ )ALL_CAPABILITIES = frozenset( IntegrationCapability )diff --git a/src/hi/integrations/importer/integration_importer.py b/src/hi/integrations/importer/integration_importer.pyindex 394b47a2..27953037 100644--- a/src/hi/integrations/importer/integration_importer.py+++ b/src/hi/integrations/importer/integration_importer.py@@ -11,11 +11,10 @@ candidate-listing, item ingest, and discard operations."""from typing import List+from hi.integrations.capability_gateway import CapabilityGateway+from hi.integrations.enums import IntegrationCapabilityfrom hi.integrations.models import IntegrationAttribute-from hi.integrations.transient_models import (- IntegrationMetaData,- IntegrationValidationResult,-)+from hi.integrations.transient_models import IntegrationValidationResultfrom .transient_models import (CandidateItem,@@ -24,10 +23,9 @@ from .transient_models import ()-class IntegrationImporter:+class IntegrationImporter( CapabilityGateway ):- def get_metadata(self) -> IntegrationMetaData:- raise NotImplementedError('Subclasses must override this method')+ capability = IntegrationCapability.IMPORTdef validate_configuration(self,diff --git a/src/hi/integrations/importer/views.py b/src/hi/integrations/importer/views.pyindex 6aeb45fd..d4a21706 100644--- a/src/hi/integrations/importer/views.py+++ b/src/hi/integrations/importer/views.py@@ -75,6 +75,9 @@ class ImporterConfigureView( CapabilityConfigureView ):template_name = 'integrations/importer/modals/importer_configure.html'error_title = 'Cannot configure import.'+ def get_capability_gateway( self, integration_data ):+ return integration_data.integration_gateway.get_importer()+def handle_post_success(self, request, integration_data):# Synchronously refresh the integration's singleton manager so# the freshly-saved credentials are visible before the importerdiff --git a/src/hi/integrations/integration_attribute_edit_context.py b/src/hi/integrations/integration_attribute_edit_context.pyindex e52fa6a0..259e435d 100644--- a/src/hi/integrations/integration_attribute_edit_context.py+++ b/src/hi/integrations/integration_attribute_edit_context.py@@ -14,7 +14,7 @@ from hi.apps.attribute.forms import AttributeUploadFormfrom hi.apps.attribute.models import AttributeModelfrom hi.apps.system.health_status import HealthStatus-from hi.integrations.enums import IntegrationCapability+from hi.integrations.capability_gateway import CapabilityGatewayfrom hi.integrations.forms import IntegrationAttributeRegularFormSetfrom hi.integrations.models import Integration, IntegrationAttributefrom hi.integrations.transient_models import IntegrationKey@@ -25,14 +25,20 @@ from .integration_data import IntegrationDataclass IntegrationAttributeItemEditContext(AttributeItemEditContext):"""Integration-specific context provider for attribute editing templates.-+This class encapsulates Integration-specific knowledge while providingthe generic interface expected by attribute editing templates.++ Construction takes the active ``CapabilityGateway`` directly (rather+ than the capability enum). The instance carries both the capability+ identity (``capability_gateway.capability``) used for attribute+ filtering and the capability-specific UI hooks (description,+ attribute-form action template) the rendered templates consult."""-+def __init__( self,integration_data : IntegrationData,- capability : IntegrationCapability,+ capability_gateway : Optional[ CapabilityGateway ],health_status : HealthStatus = None,update_button_label : str = 'UPDATE',suppress_history : bool = False,@@ -40,7 +46,15 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):) -> None:super().__init__( owner_type = 'integration', owner = integration_data.integration )self.integration_data = integration_data- self._capability = capability+ self._capability_gateway = capability_gateway+ # capability_gateway may be None in legacy paths (e.g., an+ # integration declares a capability metadata-side but+ # exposes no implementation instance). The attribute+ # queryset falls back to "no capability filter" in that+ # case, which preserves existing behavior.+ self._capability = (+ capability_gateway.capability if capability_gateway is not None else None+ )self._health_status = health_statusself._update_button_label = update_button_labelself._suppress_history = suppress_history@@ -99,7 +113,7 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):integration_name = str( member ),).integration_key_strfor member in AttributeType- if self._capability in member.capabilities+ if self._capability is None or self._capability in member.capabilities]return self.integration.attributes.filter(integration_key_str__in = key_strs,@@ -120,5 +134,6 @@ class IntegrationAttributeItemEditContext(AttributeItemEditContext):template_context.update({'integration_data': self.integration_data,'health_status': self._health_status,+ 'capability_gateway': self._capability_gateway,})return template_contextdiff --git a/src/hi/integrations/integration_gateway.py b/src/hi/integrations/integration_gateway.pyindex 53ef16ab..91a093e8 100644--- a/src/hi/integrations/integration_gateway.py+++ b/src/hi/integrations/integration_gateway.py@@ -6,6 +6,9 @@ from hi.apps.entity.entity_placement import ()from hi.apps.entity.models import Entity+from hi.integrations.referencer.integration_referencer import (+ IntegrationAttributeReferencer,+)from hi.integrations.connector.integration_connector import IntegrationConnectorfrom hi.integrations.importer.integration_importer import IntegrationImporterfrom hi.integrations.models import IntegrationAttribute@@ -59,6 +62,17 @@ class IntegrationGateway:"""return None+ def get_attribute_referencer(self) -> Optional[IntegrationAttributeReferencer]:+ """+ Return the integration's attribute-referencer when it+ supports the ATTRIBUTE_REFERENCE capability; None otherwise.+ Parallel to get_connector() and get_importer(). The+ framework owns the picker UI and the TEXT-attribute attach+ lifecycle; the referencer supplies the integration-specific+ search-against-upstream operation.+ """+ return None+def validate_configuration(self,integration_attributes: List[IntegrationAttribute]diff --git a/src/hi/integrations/referencer/__init__.py b/src/hi/integrations/referencer/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/hi/integrations/referencer/integration_referencer.py b/src/hi/integrations/referencer/integration_referencer.pynew file mode 100644index 00000000..180c4e51--- /dev/null+++ b/src/hi/integrations/referencer/integration_referencer.py@@ -0,0 +1,70 @@+"""+Per-integration ATTRIBUTE_REFERENCE base class.++Parallel to ``IntegrationConnector`` (CONNECT capability) and+``IntegrationImporter`` (IMPORT capability). Each integration that+advertises ``IntegrationCapability.ATTRIBUTE_REFERENCE`` provides a+concrete subclass and returns an instance from+``IntegrationGateway.get_attribute_referencer()``. The framework+owns the picker UI, attach lifecycle, and TEXT-attribute creation;+the integration participates by translating a search query into a+list of ``AttributeReferenceResult`` candidates.+"""++from typing import List, Optional++from hi.integrations.capability_gateway import CapabilityGateway+from hi.integrations.enums import IntegrationCapability+from hi.integrations.models import IntegrationAttribute+from hi.integrations.transient_models import IntegrationValidationResult++from .transient_models import AttributeReferenceResult+++class IntegrationAttributeReferencer( CapabilityGateway ):++ """Search-and-attach surface contributed by integrations that+ expose a queryable corpus of linkable resources (documents,+ pages, files in an external CMS, etc.). The framework calls+ ``search_references`` from the picker view and presents the+ returned candidates to the operator for multi-select attach."""++ capability = IntegrationCapability.ATTRIBUTE_REFERENCE++ def validate_configuration(+ self,+ integration_attributes: List[IntegrationAttribute],+ ) -> IntegrationValidationResult:+ """Schema-only validation of the proposed configuration.+ Must NOT perform network operations. Mirrors the contract+ for the same operation on the Connect / Import sides."""+ raise NotImplementedError('Subclasses must override this method')++ def search_references(+ self,+ query: str,+ limit: int = 20,+ ) -> List[AttributeReferenceResult]:+ """Query the upstream corpus and return up to ``limit``+ candidates. Operators see the returned list rendered as+ cards (thumbnail/mime-icon + title + snippet + clickable+ source URL); multi-selecting any subset attaches them as+ TEXT attributes on the host Entity or Location.++ Implementations should:+ - Return an empty list when the query yields no matches.+ - Honor ``limit`` as an upper bound (the picker uses a+ user-selectable page-size 20/50/100).+ - Order results by upstream relevance (most-relevant+ first); the picker preserves this order.+ - Not raise on empty/whitespace queries; return [].+ """+ raise NotImplementedError('Subclasses must override this method')++ def get_attribute_actions_template_name(self) -> Optional[str]:+ """Per-capability template fragment to render in the+ integration attribute form's action bar. ATTRIBUTE_REFERENCE+ contributes the enabled/disabled status badge plus the+ Disable button. Individual integrations can override to+ substitute their own fragment."""+ return 'integrations/referencer/panes/attribute_actions.html'diff --git a/src/hi/integrations/referencer/transient_models.py b/src/hi/integrations/referencer/transient_models.pynew file mode 100644index 00000000..f5165cb5--- /dev/null+++ b/src/hi/integrations/referencer/transient_models.py@@ -0,0 +1,34 @@+"""+Transient (non-persisted) models for the ATTRIBUTE_REFERENCE+capability.++``AttributeReferenceResult`` is the picker-only view of an upstream+document or other linkable resource: shown in the search modal,+selected by the operator, and discarded once the resulting+``EntityAttribute`` / ``LocationAttribute`` row is created. Only+``title`` and ``source_url`` survive into persistent storage; the+remaining fields exist solely for picker UX.++Wire-format strings (form field names, JSON record keys) shared+between the picker views, templates, and ``attr-picker.js`` live in+``hi.constants.DIVID`` (mirrored in ``static/js/main.js``). See the+``ATTR_PICKER_*`` entries there.+"""++from dataclasses import dataclass+from typing import Optional+++@dataclass(frozen=True)+class AttributeReferenceResult:+ """One row in the picker's result list.++ ``title`` and ``source_url`` are the only fields that survive+ the attach step — they become the attribute's ``name`` and+ ``value`` respectively. Everything else is picker chrome.+ """+ title: str+ source_url: str+ thumbnail_url: Optional[str] = None+ mime_type: Optional[str] = None+ snippet: Optional[str] = Nonediff --git a/src/hi/integrations/referencer/urls.py b/src/hi/integrations/referencer/urls.pynew file mode 100644index 00000000..c02313ed--- /dev/null+++ b/src/hi/integrations/referencer/urls.py@@ -0,0 +1,26 @@+from django.urls import path, re_path++from . import views+++urlpatterns = [+ path( 'picker/',+ views.AttributeReferencePickerView.as_view(),+ name='integrations_attribute_reference_picker' ),++ path( 'picker/search/',+ views.AttributeReferenceSearchView.as_view(),+ name='integrations_attribute_reference_search' ),++ path( 'picker/attach/',+ views.AttributeReferenceAttachView.as_view(),+ name='integrations_attribute_reference_attach' ),++ path( 'home/',+ views.ReferenceHomeView.as_view(),+ name='integrations_reference_home' ),++ re_path( r'^manage/(?P<integration_id>[\w\-]*)$',+ views.ReferenceManageView.as_view(),+ name='integrations_reference_manage' ),+]diff --git a/src/hi/integrations/referencer/views.py b/src/hi/integrations/referencer/views.pynew file mode 100644index 00000000..3c753873--- /dev/null+++ b/src/hi/integrations/referencer/views.py@@ -0,0 +1,577 @@+"""+ATTRIBUTE_REFERENCE picker — one HiModal view backed by antinode+partial swaps.++Workflow:++ - GET ``/integrations/referencer/picker/`` with ``item_type`` ++ ``item_id`` query params renders the full picker modal. The+ action-bar "LINK" button in EntityEdit / LocationEdit opens+ the modal via ``data-async="modal"``. The view discovers all+ currently-enabled ATTRIBUTE_REFERENCE integrations and lets+ the operator choose between them via an in-modal selector+ when more than one is configured.++ - POST to the same URL re-renders the picker body. The form+ carries ``integration_id`` as a hidden field so the view knows+ which referencer to drive the search against. The form's+ ``data-async="#picker-body-<uuid>"`` + ``data-stay-in-modal``+ keeps the modal open while the body partial swaps in.++ - When the operator submits with ``action=attach``, the view+ creates one TEXT attribute per current selection on the host+ Entity / Location and returns ``antinode.refresh_response()`` to+ reload the parent page (modal closes via page reload).++Multi-select state is server-driven via three form fields:+``selections_json`` (canonical existing list, hidden), ``visible_url``+(hidden per result; identifies what was rendered), and ``result_url``+(checkbox value per result; only submitted when checked). The view+computes the new selection list each POST: existing + newly checked+- unchecked visibles ± an explicit ``remove_url`` if the operator+clicked a chip's × button.+"""++import json+import logging+from typing import Dict, List++from django.core.exceptions import BadRequest+from django.db import transaction+from django.http import Http404, HttpResponse+from django.template.loader import render_to_string+from django.urls import reverse+from django.views.generic import View++from hi.apps.attribute.edit_form_handler import AttributeEditFormHandler+from hi.apps.attribute.edit_response_renderer import AttributeEditResponseRenderer+from hi.apps.attribute.enums import AttributeType, AttributeValueType+from hi.apps.attribute.view_mixins import AttributeEditViewMixin+from hi.apps.common import antinode+from hi.apps.config.enums import ConfigPageType+from hi.apps.config.views import ConfigPageView+from hi.apps.entity.models import Entity, EntityAttribute+from hi.apps.location.models import Location, LocationAttribute+from hi.constants import DIVID+from hi.enums import ItemType+from hi.exceptions import ForceRedirectException+from hi.hi_async_view import HiModalView++from hi.integrations.enums import IntegrationCapability+from hi.integrations.integration_attribute_edit_context import (+ IntegrationAttributeItemEditContext,+)+from hi.integrations.integration_data import IntegrationData+from hi.integrations.integration_manager import IntegrationManager+from hi.integrations.view_mixins import IntegrationViewMixin++from .integration_referencer import IntegrationAttributeReferencer+from .transient_models import AttributeReferenceResult+++logger = logging.getLogger(__name__)+++_PAGE_SIZE_CHOICES = (20, 50, 100)+_DEFAULT_LIMIT = 20+_MAX_LIMIT = 100++# ItemType → (owner model, attribute model, owner FK field name).+_ATTRIBUTE_OWNER_MODELS = {+ ItemType.ENTITY: (Entity, EntityAttribute, 'entity'),+ ItemType.LOCATION: (Location, LocationAttribute, 'location'),+}+++def _get_referencer_integration_data_list() -> List[ IntegrationData ]:+ """All currently-enabled integrations that advertise the+ ATTRIBUTE_REFERENCE capability. Returned in label order+ (the manager already sorts by label)."""+ return IntegrationManager().get_integration_data_list(+ enabled_only=True,+ capabilities=frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),+ )+++def _resolve_integration_data(+ integration_data_list: List[ IntegrationData ],+ integration_id: str,+) -> IntegrationData:+ """Map the form's posted integration_id to one of the+ currently-enabled referencer integrations. Rejects unknown+ or now-disabled ids so a stale modal can't drive a search+ against an integration the operator has turned off."""+ if not integration_id:+ raise BadRequest(+ f'Missing {DIVID["ATTR_PICKER_INTEGRATION_ID_FIELD"]}.',+ )+ for candidate in integration_data_list:+ if candidate.integration_id == integration_id:+ return candidate+ raise BadRequest(+ f'Unknown {DIVID["ATTR_PICKER_INTEGRATION_ID_FIELD"]}: '+ f'{integration_id!r}',+ )+++def _require_referencer(+ integration_data: IntegrationData,+ request,+) -> IntegrationAttributeReferencer:+ referencer = integration_data.integration_gateway.get_attribute_referencer()+ if referencer is None:+ raise Http404( request )+ return referencer+++def _parse_item_type(raw_value: str) -> ItemType:+ try:+ item_type = ItemType.from_name( raw_value )+ except ValueError:+ raise BadRequest(+ f'Unsupported {DIVID["ATTR_PICKER_ITEM_TYPE_FIELD"]}: {raw_value!r}',+ )+ if item_type not in _ATTRIBUTE_OWNER_MODELS:+ raise BadRequest(+ f'Unsupported {DIVID["ATTR_PICKER_ITEM_TYPE_FIELD"]}: {raw_value!r}',+ )+ return item_type+++def _parse_item_id(raw_value) -> int:+ try:+ return int( raw_value )+ except (TypeError, ValueError):+ raise BadRequest(+ f'Invalid {DIVID["ATTR_PICKER_ITEM_ID_FIELD"]}.',+ )+++def _parse_limit(raw_limit) -> int:+ try:+ limit = int( raw_limit )+ except (TypeError, ValueError):+ return _DEFAULT_LIMIT+ if limit not in _PAGE_SIZE_CHOICES:+ return _DEFAULT_LIMIT+ return min( limit, _MAX_LIMIT )+++def _resolve_owner(item_type: ItemType, item_id: int):+ owner_model, _attribute_model, _owner_field = _ATTRIBUTE_OWNER_MODELS[ item_type ]+ try:+ return owner_model.objects.get( id=item_id )+ except owner_model.DoesNotExist:+ raise Http404( f'{item_type.label} not found.' )+++def _search_upstream(+ referencer: IntegrationAttributeReferencer,+ query: str,+ limit: int,+) -> List[ AttributeReferenceResult ]:+ if not query:+ return []+ try:+ return referencer.search_references( query=query, limit=limit )+ except Exception:+ logger.exception( 'Attribute-reference search failed.' )+ return []+++def _parse_selections_json(raw: str) -> List[ Dict[str, str] ]:+ """Parse the JS-built ``selections_json`` payload submitted on+ attach. Skips records with missing title or source_url and+ falls back to an empty list on any decode error."""+ if not raw:+ return []+ try:+ decoded = json.loads( raw )+ except json.JSONDecodeError:+ return []+ if not isinstance( decoded, list ):+ return []+ parsed: List[ Dict[str, str] ] = []+ for item in decoded:+ if not isinstance( item, dict ):+ continue+ title = ( item.get( DIVID['ATTR_PICKER_SELECTION_TITLE_KEY'] ) or '' ).strip()+ url = ( item.get( DIVID['ATTR_PICKER_SELECTION_URL_KEY'] ) or '' ).strip()+ if not title or not url:+ continue+ parsed.append( {+ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: title,+ DIVID['ATTR_PICKER_SELECTION_URL_KEY']: url,+ } )+ return parsed+++def _create_attributes(+ item_type: ItemType,+ owner,+ selections: List[ Dict[str, str] ],+) -> List[ int ]:+ if not selections:+ return []+ _owner_model, attribute_model, owner_field = _ATTRIBUTE_OWNER_MODELS[ item_type ]+ created_ids: List[ int ] = []+ with transaction.atomic():+ for selection in selections:+ attr = attribute_model.objects.create( **{+ owner_field: owner,+ 'name': selection[ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY'] ][:64],+ 'value': selection[ DIVID['ATTR_PICKER_SELECTION_URL_KEY'] ],+ 'value_type_str': str( AttributeValueType.TEXT ),+ 'attribute_type_str': str( AttributeType.CUSTOM ),+ 'is_editable': True,+ 'is_required': False,+ } )+ created_ids.append( attr.id )+ return created_ids+++class AttributeReferencePickerView( HiModalView ):+ """GET the picker modal. Initial render is empty — no results,+ no selections. Selection state lives in JS (see+ ``static/js/attr-picker.js``); subsequent search results arrive+ via async POST to ``integrations_attribute_reference_search``,+ and the final commit posts to+ ``integrations_attribute_reference_attach``."""++ MODAL_TEMPLATE_NAME = 'integrations/referencer/modals/attr_picker.html'++ def get_template_name(self) -> str:+ return self.MODAL_TEMPLATE_NAME++ def get(self, request, *args, **kwargs):+ integration_data_list = _get_referencer_integration_data_list()+ if not integration_data_list:+ raise Http404( request )++ item_type = _parse_item_type(+ request.GET.get( DIVID['ATTR_PICKER_ITEM_TYPE_FIELD'] ),+ )+ item_id = _parse_item_id(+ request.GET.get( DIVID['ATTR_PICKER_ITEM_ID_FIELD'] ),+ )+ owner = _resolve_owner( item_type=item_type, item_id=item_id )++ # Default to the first configured referencer. The operator+ # can switch via the picker's integration <select> when more+ # than one referencer is configured.+ integration_data = integration_data_list[0]++ # Seed the picker with a query based on the owner's name so+ # the operator opens to relevant results without retyping+ # what they're already configuring. Goes through the same+ # ``_search_upstream`` the search endpoint uses; the body+ # template's results container renders the same+ # ``attr_picker_results.html`` partial the search response+ # returns.+ query = owner.name+ referencer = integration_data.integration_gateway.get_attribute_referencer()+ results = _search_upstream(+ referencer=referencer,+ query=query,+ limit=_DEFAULT_LIMIT,+ ) if referencer is not None else []++ context = {+ 'integration_data_list': integration_data_list,+ 'integration_data': integration_data,+ 'item_type_value': str( item_type ),+ 'item_id': owner.id,+ 'limit': _DEFAULT_LIMIT,+ 'page_size_choices': _PAGE_SIZE_CHOICES,+ 'query': query,+ 'results': results,+ }+ return self.modal_response( request, context=context )+++class AttributeReferenceSearchView( View ):+ """POST endpoint that runs an upstream search and returns only+ the result-cards HTML partial. The attr-picker JS swaps the+ returned markup into the picker's results container, then+ re-applies checkbox state from its in-memory selection set.++ Empty / whitespace queries short-circuit to an empty result+ partial (no upstream call)."""++ RESULTS_TEMPLATE_NAME = 'integrations/referencer/panes/attr_picker_results.html'++ def post(self, request, *args, **kwargs):+ integration_data_list = _get_referencer_integration_data_list()+ if not integration_data_list:+ raise Http404( request )+ integration_data = _resolve_integration_data(+ integration_data_list=integration_data_list,+ integration_id=request.POST.get(+ DIVID['ATTR_PICKER_INTEGRATION_ID_FIELD'],+ ),+ )+ referencer = _require_referencer( integration_data, request )+ query = (+ request.POST.get( DIVID['ATTR_PICKER_QUERY_FIELD'] ) or ''+ ).strip()+ limit = _parse_limit(+ request.POST.get( DIVID['ATTR_PICKER_LIMIT_FIELD'] ),+ )+ results = _search_upstream(+ referencer=referencer, query=query, limit=limit,+ )+ html = render_to_string(+ self.RESULTS_TEMPLATE_NAME,+ {+ 'query': query,+ 'results': results,+ },+ request=request,+ )+ return HttpResponse( html )+++class AttributeReferenceAttachView( View ):+ """POST endpoint that creates TEXT attributes for the operator's+ selected references. The JS module serializes its in-memory+ selection set into ``selections_json`` just before the form+ submits.++ Returns ``antinode.refresh_response()`` so the parent page+ reloads and the modal closes naturally."""++ def post(self, request, *args, **kwargs):+ item_type = _parse_item_type(+ request.POST.get( DIVID['ATTR_PICKER_ITEM_TYPE_FIELD'] ),+ )+ item_id = _parse_item_id(+ request.POST.get( DIVID['ATTR_PICKER_ITEM_ID_FIELD'] ),+ )+ owner = _resolve_owner( item_type=item_type, item_id=item_id )+ selections = _parse_selections_json(+ request.POST.get( DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD'] ) or '',+ )+ _create_attributes(+ item_type=item_type, owner=owner, selections=selections,+ )+ return antinode.refresh_response()+++# ----------------------------------------------------------------------+# Reference-capability management page+# ----------------------------------------------------------------------+#+# Parallel to the Connectors page (CONNECT capability) and the Data+# Import page (IMPORT capability). The operator-facing tab label is+# "Content Sources"; code-side naming uses ``reference`` to align+# with the capability and the surrounding referencer/ directory.+++class ReferenceHomeView( ConfigPageView, IntegrationViewMixin ):+ """Landing route for the reference-management page. Picks the+ first ATTRIBUTE_REFERENCE integration (enabled or not) and+ redirects to its manage URL. Returns the empty-state template+ when none are discovered (defensive — currently can't happen+ at runtime as long as the paperless app is installed)."""++ def config_page_type(self) -> ConfigPageType:+ return ConfigPageType.INTEGRATIONS_REFERENCE++ def get_main_template_name( self ) -> str:+ return 'integrations/referencer/pages/no_integrations.html'++ def get_main_template_context( self, request, *args, **kwargs ):+ integration_data_list = IntegrationManager().get_integration_data_list(+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),+ )+ if not integration_data_list:+ return dict()+ redirect_url = reverse(+ 'integrations_reference_manage',+ kwargs = { 'integration_id': integration_data_list[0].integration_id },+ )+ raise ForceRedirectException( redirect_url )+++class ReferenceManageView( ConfigPageView, IntegrationViewMixin, AttributeEditViewMixin ):+ """Per-integration attribute-form page for ATTRIBUTE_REFERENCE+ integrations.++ Differences from ``ConnectorManageView``:+ - Filters by ATTRIBUTE_REFERENCE (not CONNECT).+ - Does not read health status / sync-check state /+ has_entities; ATTRIBUTE_REFERENCE has no monitors and no+ sync cycle.+ - Passes ``capability = ATTRIBUTE_REFERENCE`` to the attribute+ edit context so the attribute queryset is filtered to the+ attributes the capability declares.+ - Tolerates ``is_enabled = False`` integrations — the operator+ configures credentials here before the integration is+ enabled.+ """++ def config_page_type(self) -> ConfigPageType:+ return ConfigPageType.INTEGRATIONS_REFERENCE++ def get_main_template_name( self ) -> str:+ return 'integrations/referencer/pages/integration_manage.html'++ def get_main_template_context( self, request, *args, **kwargs ):+ integration_data, integration_data_list = self._resolve(+ kwargs.get( 'integration_id' )+ )+ attr_item_context = self._build_attr_item_context( integration_data )++ template_context = self.create_initial_template_context(+ attr_item_context = attr_item_context,+ )+ template_context.update({+ 'core': {+ 'integration_data_list': integration_data_list,+ 'integration_data': integration_data,+ },+ })+ return template_context++ ACTION_DISABLE = 'disable'++ def post( self, request, *args, **kwargs ):+ integration_data, _ = self._resolve( kwargs.get( 'integration_id' ) )+ if request.POST.get( 'action' ) == self.ACTION_DISABLE:+ return self._handle_disable( request, integration_data )+ return self._handle_save( request, integration_data )++ def _handle_disable( self, request, integration_data ):+ """Flip ``is_enabled`` to False; credentials remain in the DB+ so a future ENABLE is one click. Re-renders the form area in+ place so the badge and the submit-button label update via+ antinode partial swap without a full page reload."""+ if integration_data.integration.is_enabled:+ integration_data.integration.is_enabled = False+ integration_data.integration.save(+ update_fields = [ 'is_enabled' ],+ )+ attr_item_context = self._build_attr_item_context( integration_data )+ renderer = AttributeEditResponseRenderer()+ return renderer.render_form_success_response(+ attr_item_context = attr_item_context,+ request = request,+ message = None,+ )++ def _handle_save( self, request, integration_data ):+ # Capture pre-save enabled state so we can flip it on a+ # successful first-time save (the ``ENABLE`` flow).+ was_enabled = integration_data.integration.is_enabled+ attr_item_context = self._build_attr_item_context( integration_data )++ form_handler = AttributeEditFormHandler()+ renderer = AttributeEditResponseRenderer()+ edit_form_data = form_handler.create_edit_form_data(+ attr_item_context = attr_item_context,+ form_data = request.POST,+ )++ forms_valid = form_handler.validate_forms( edit_form_data = edit_form_data )+ if forms_valid:+ # Schema + access check via the shared helper; populates+ # ``_non_form_errors`` on failure so the next is_valid()+ # call returns False.+ self.validate_attributes_extra(+ attr_item_context = attr_item_context,+ regular_attributes_formset = edit_form_data.regular_attributes_formset,+ request = request,+ )+ forms_valid = edit_form_data.regular_attributes_formset.is_valid()++ if not forms_valid:+ return renderer.render_form_error_response(+ attr_item_context = attr_item_context,+ edit_form_data = edit_form_data,+ request = request,+ )++ form_handler.save_forms(+ attr_item_context = attr_item_context,+ edit_form_data = edit_form_data,+ request = request,+ )+ if not was_enabled:+ # First-time ENABLE: credentials just validated upstream+ # via the helper's access probe, so flipping is_enabled+ # to True reflects what's now true on the wire.+ integration_data.integration.is_enabled = True+ integration_data.integration.save(+ update_fields = [ 'is_enabled' ],+ )+ # Rebuild the edit context so the response renders the+ # post-flip state: ``update_button_label`` flips from+ # ENABLE to UPDATE and the action-bar fragment reads+ # ``is_enabled = True``.+ attr_item_context = self._build_attr_item_context( integration_data )++ return renderer.render_form_success_response(+ attr_item_context = attr_item_context,+ request = request,+ message = None,+ )++ def validate_attributes_extra( self, attr_item_context,+ regular_attributes_formset, request ):+ # The shared helper runs both gateway.validate_configuration+ # (schema) and gateway.validate_access (live probe) and+ # decorates the formset with the failure message on either+ # failure. We deliberately want the access probe on every+ # save so a credential typo on UPDATE-while-enabled is+ # rejected (atomic semantics — nothing changes on failure).+ self.validate_attributes_extra_helper(+ attr_item_context,+ regular_attributes_formset,+ error_title = 'Cannot save settings.',+ )+ return++ def _resolve( self, integration_id ):+ integration_data_list = IntegrationManager().get_integration_data_list(+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),+ )+ if not integration_data_list:+ raise Http404( 'No reference integrations are installed.' )+ integration_data = self._find_integration_data(+ integration_data_list = integration_data_list,+ integration_id = integration_id,+ )+ if integration_data is None:+ raise Http404(+ f'Unknown reference integration: {integration_id!r}'+ )+ return integration_data, integration_data_list++ def _build_attr_item_context( self, integration_data ):+ # Button label flips with enabled state: ``ENABLE`` is the+ # first-time activation path; ``UPDATE`` is the+ # already-enabled re-validate-and-save path. Both share the+ # same form-submission endpoint and the same validation+ # gates — only the label and the post-save bookkeeping+ # differ.+ update_label = (+ 'UPDATE' if integration_data.integration.is_enabled else 'ENABLE'+ )+ return IntegrationAttributeItemEditContext(+ integration_data = integration_data,+ capability_gateway = integration_data.integration_gateway.get_attribute_referencer(),+ health_status = None,+ update_button_label = update_label,+ )++ @staticmethod+ def _find_integration_data(+ integration_data_list: List[ IntegrationData ],+ integration_id: str,+ ) -> IntegrationData:+ for candidate in integration_data_list:+ if candidate.integration_id == integration_id:+ return candidate+ return None++diff --git a/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html b/src/hi/integrations/templates/integrations/connector/modals/integration_disable.htmlindex 5cc38989..ab68de16 100644--- a/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html+++ b/src/hi/integrations/templates/integrations/connector/modals/integration_disable.html@@ -15,13 +15,14 @@{% endblock %}{% block body %}-<h4>Disable {{ integration_data.label }} Integration?</h4>+ {% include "integrations/panes/integration_modal_header.html" %}+<h4>Disable {{ integration_data.label }} Connector?</h4>{% if removal_summary.total_count == 0 %}-<p>This integration has no attached items.</p>+<p>This connector has no attached items.</p>{% elif removal_summary.has_mixed_state %}<p>- This integration has <strong>{{ removal_summary.total_count }}</strong>+ This connector has <strong>{{ removal_summary.total_count }}</strong>{% if removal_summary.total_count == 1 %}item{% else %}items{% endif %}.<strong>{{ removal_summary.user_data_count }}</strong> of{% if removal_summary.user_data_count == 1 %}them has{% else %}them have{% endif %}@@ -32,7 +33,7 @@<strong>DELETE SAFE</strong> — delete the {{ removal_summary.deletable_count }}{% if removal_summary.deletable_count == 1 %}item{% else %}items{% endif %}without custom data, and preserve the {{ removal_summary.user_data_count }} with custom- data (detached from this integration; the items will show as+ data (detached from this connector; the items will show as<em>Detached from {{ integration_data.label }}</em> in the entity-detail UI,with custom attributes and layout retained).</li>@@ -45,14 +46,14 @@</ul>{% else %}<p>- This integration has <strong>{{ removal_summary.total_count }}</strong>+ This connector has <strong>{{ removal_summary.total_count }}</strong>{% if removal_summary.total_count == 1 %}item{% else %}items{% endif %}.None have custom data you've added, so all will be deleted.</p>{% endif %}<p class="text-muted small">- Configuration values are retained. If you re-configure this integration+ Configuration values are retained. If you re-configure this connectorlater, it will start fresh without reconnecting to any preserved items.</p>{% endblock %}diff --git a/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html b/src/hi/integrations/templates/integrations/connector/modals/integration_enable.htmlindex 53df3ed9..5375a187 100644--- a/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html+++ b/src/hi/integrations/templates/integrations/connector/modals/integration_enable.html@@ -2,9 +2,11 @@{% load icons %}{% block modal_dialog_class %}hi-modal-dialog-600{% endblock %}-{% block title_text %}{{ integration_data.label }} Integration{% endblock %}+{% block title_text %}{{ integration_data.label }} Connector{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+<!-- Root container for this attribute editing context --><div id="{{ attr_page_context.container_html_id }}"class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}">diff --git a/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html b/src/hi/integrations/templates/integrations/connector/modals/integrations_select.htmlindex 94f030aa..8dddf148 100644--- a/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html+++ b/src/hi/integrations/templates/integrations/connector/modals/integrations_select.html@@ -4,7 +4,7 @@{% block modal_dialog_class %}hi-modal-dialog-700{% endblock %}{% block title_text %}-All Integrations+All Connectors{% endblock %}{% block body %}@@ -48,6 +48,6 @@ All Integrations</div></div>{% empty %}-<div class="alert alert-warning"> No integrations found.</div>+<div class="alert alert-warning"> No connectors found.</div>{% endfor %}{% endblock %}diff --git a/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html b/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.htmlindex ce301e50..c0277f42 100644--- a/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html+++ b/src/hi/integrations/templates/integrations/connector/modals/pre_sync_confirm.html@@ -30,7 +30,7 @@ Context:(initial CONNECT); False for subsequentupdate-check operations.sync_description : Optional[str] — per-integration text from- IntegrationConnector.get_description.+ IntegrationConnector.get_sync_description.sync_url : str (required) — URL the form posts to.removal_summary : Optional[IntegrationRemovalSummary] —integration's user-data classification.@@ -53,6 +53,8 @@ Check {{ integration_data.label }} for updates?{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+{% if is_initial_connect %}<p>Connect will pull items from <strong>{{ integration_data.label }}</strong>@@ -67,7 +69,7 @@ Check {{ integration_data.label }} for updates?</p>{% if removal_summary.has_mixed_state %}<p>- This integration has <strong>{{ removal_summary.user_data_count }}</strong>+ This connector has <strong>{{ removal_summary.user_data_count }}</strong>{% if removal_summary.user_data_count == 1 %}item{% else %}items{% endif %}with custom data you've added. If an update would drop{% if removal_summary.user_data_count == 1 %}that item{% else %}any of them{% endif %}:@@ -75,7 +77,7 @@ Check {{ integration_data.label }} for updates?<ul><li><strong>RETAIN MISSING</strong> — preserve any missing items with custom data- (detached from this integration; they will show as+ (detached from this connector; they will show as<em>Detached from {{ integration_data.label }}</em> in the entity-detail UI,with custom attributes and layout retained).</li>diff --git a/src/hi/integrations/templates/integrations/connector/modals/sync_result.html b/src/hi/integrations/templates/integrations/connector/modals/sync_result.htmlindex 4a97b6fd..eb967e67 100644--- a/src/hi/integrations/templates/integrations/connector/modals/sync_result.html+++ b/src/hi/integrations/templates/integrations/connector/modals/sync_result.html@@ -38,16 +38,7 @@{% endblock %}{% block body %}-{% if integration_data %}-<div class="d-flex align-items-center mb-3 pb-2 border-bottom">- <img class="mr-2 hi-integration-logo"- src="{% static integration_data.integration_metadata.logo_static_path %}"- alt="{{ integration_data.label }} Logo">- <div class="text-muted small text-uppercase hi-uppercase-label">- {{ integration_data.label }}- </div>-</div>-{% endif %}+{% include "integrations/panes/integration_modal_header.html" %}{% comment %}Hero headline — the operator's first read of the modal. Errorsdiff --git a/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html b/src/hi/integrations/templates/integrations/connector/pages/integration_manage.htmlindex 073de00a..46b07301 100644--- a/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html+++ b/src/hi/integrations/templates/integrations/connector/pages/integration_manage.html@@ -8,7 +8,7 @@<a class="btn btn-outline-primary w-100" role="button"href="{% url 'integrations_connect_select' %}"data-async="modal">- {% icon "settings" size="sm" css_class="hi-icon-left" %}INTEGRATIONS+ {% icon "settings" size="sm" css_class="hi-icon-left" %}CONNECTORS</a></div>{% for item in core.sidebar_items %}diff --git a/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html b/src/hi/integrations/templates/integrations/connector/pages/no_integrations.htmlindex 9bfd2011..8258e9f3 100644--- a/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html+++ b/src/hi/integrations/templates/integrations/connector/pages/no_integrations.html@@ -1,13 +1,13 @@{% extends "config/pages/config_base.html" %}{% block config_content %}<div class="alert alert-info text-center m-4">- There are no integrations currently configured.+ There are no connectors currently configured.</div><div class="text-center m-4 p-4"><a class="btn btn-primary btn-lg" role="button"href="{% url 'integrations_connect_select' %}"data-async="modal">- CONFIGURE INTEGRATIONS+ CONFIGURE CONNECTORS</a></div>{% endblock %}diff --git a/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.html b/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.htmlnew file mode 100644index 00000000..f668bc1c--- /dev/null+++ b/src/hi/integrations/templates/integrations/connector/panes/connect_attribute_actions.html@@ -0,0 +1,20 @@+{% comment %}+Attribute-form action-bar fragment for the CONNECT capability:+health-status badge linking to the health-detail modal. Rendered+when ``health_status`` is in scope (the CONNECT manage view passes+it; modals that include this body do not).++Context (inherited from the surrounding edit body):+ health_status : HealthStatus (optional)+ integration_data : IntegrationData (required)+{% endcomment %}+{% if health_status %}+<div class="ml-3">+ <a href="{% url 'integrations_connect_health_status' integration_id=integration_data.integration_id %}"+ class="btn btn-link p-0 d-flex align-items-center text-decoration-none"+ data-async="modal"+ title="View health status details">+ {% include "system/panes/health_status_badge.html" with health_status=health_status %}+ </a>+</div>+{% endif %}diff --git a/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html b/src/hi/integrations/templates/integrations/importer/modals/data_import_info.htmlindex 4e32ef8e..a5e83b4f 100644--- a/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html+++ b/src/hi/integrations/templates/integrations/importer/modals/data_import_info.html@@ -3,23 +3,17 @@{% block modal_dialog_class %}hi-modal-dialog-600{% endblock %}{% block title_text %}-Data Import vs. Integration+Data Import vs. Connector{% endblock %}{% block body %}<p><strong>Data Import</strong> is a one-time copy of items from an- upstream system into Home Information. Once imported, the items- are HI-owned: you can edit them freely, and they no longer depend- on the upstream source.+ external system into Home Information. Once imported: you can edit them freely,+ but changes will not be reflected in the external system.</p><p>- An <a href="{% url 'integrations_connect_home' %}">Integration</a>, in- contrast, mirrors the upstream system live — the upstream- remains the source of truth, and changes flow in via Update.-</p>-<p>- An integration may offer both modes (HomeBox today), but only- one mode's data should be active at a time for a given upstream.+ A <strong>Connector</strong>, in contrast, tracks and displays the data live — the+ external system remains the source of truth.</p>{% endblock %}diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html b/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.htmlindex 42464e30..24780fce 100644--- a/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html+++ b/src/hi/integrations/templates/integrations/importer/modals/import_discard_confirm.html@@ -15,6 +15,8 @@{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+<h4>Discard imported {{ integration_data.label }} items?</h4>{% if imported_count == 0 %}diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_preview.html b/src/hi/integrations/templates/integrations/importer/modals/import_preview.htmlindex a0d2da6e..a55b717d 100644--- a/src/hi/integrations/templates/integrations/importer/modals/import_preview.html+++ b/src/hi/integrations/templates/integrations/importer/modals/import_preview.html@@ -12,6 +12,8 @@ Import from {{ integration_data.label }}?{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+{% if error_message %}<div class="alert alert-warning">{{ error_message }}</div>{% elif new_count == 0 %}diff --git a/src/hi/integrations/templates/integrations/importer/modals/import_result.html b/src/hi/integrations/templates/integrations/importer/modals/import_result.htmlindex 55408ad3..ca9b1278 100644--- a/src/hi/integrations/templates/integrations/importer/modals/import_result.html+++ b/src/hi/integrations/templates/integrations/importer/modals/import_result.html@@ -8,14 +8,7 @@{% endblock %}{% block body %}-<div class="d-flex align-items-center mb-3 pb-2 border-bottom">- <img class="mr-2 hi-integration-logo"- src="{% static integration_data.integration_metadata.logo_static_path %}"- alt="{{ integration_data.label }} Logo">- <div class="text-muted small text-uppercase hi-uppercase-label">- {{ integration_data.label }}- </div>-</div>+{% include "integrations/panes/integration_modal_header.html" %}{% if result.error_list and not result.has_imports %}<div class="text-center mb-4">diff --git a/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html b/src/hi/integrations/templates/integrations/importer/modals/importer_configure.htmlindex 688bdb92..ddff6b35 100644--- a/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html+++ b/src/hi/integrations/templates/integrations/importer/modals/importer_configure.html@@ -5,6 +5,8 @@{% block title_text %}Import from {{ integration_data.label }}{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+<div id="{{ attr_page_context.container_html_id }}"class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}">diff --git a/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html b/src/hi/integrations/templates/integrations/importer/pages/data_import_page.htmlindex fec9250b..b5039ba4 100644--- a/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html+++ b/src/hi/integrations/templates/integrations/importer/pages/data_import_page.html@@ -20,7 +20,7 @@data-async="modal"title="What's the difference?"class="d-block text-muted small text-decoration-none mb-3">- Also available as an Integration.+ Also available as a Connector.{% icon "info-circle" size="sm" %}</a>{% endif %}@@ -42,7 +42,7 @@{% empty %}<div class="col-12"><div class="alert alert-info">- No integrations support Data Import.+ No data importers currently defined.</div></div>{% endfor %}diff --git a/src/hi/integrations/templates/integrations/modals/capability_blocked.html b/src/hi/integrations/templates/integrations/modals/capability_blocked.htmlindex dbb7989d..a2a93535 100644--- a/src/hi/integrations/templates/integrations/modals/capability_blocked.html+++ b/src/hi/integrations/templates/integrations/modals/capability_blocked.html@@ -8,6 +8,8 @@{% endblock %}{% block body %}+{% include "integrations/panes/integration_modal_header.html" %}+<h5 class="mb-3">Cannot configure as {{ my_label }}.</h5><p>{{ integration_data.label }} {{ existing_mode_clause }}diff --git a/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html b/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.htmlindex 8bb8b05c..5b964cb1 100644--- a/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html+++ b/src/hi/integrations/templates/integrations/panes/integration_edit_content_body.html@@ -12,17 +12,18 @@</a>{% endif %}-<!-- Integration Health Status Display -->-{% if health_status %}-<div class="ml-3">- <a href="{% url 'integrations_connect_health_status' integration_id=integration_data.integration_id %}"- class="btn btn-link p-0 d-flex align-items-center text-decoration-none"- data-async="modal"- title="View health status details">- {% include "system/panes/health_status_badge.html" with health_status=health_status %}- </a>-</div>+{% comment %}+Capability-owned action fragment. The active CapabilityGateway+returns its own template path; the framework template stays+capability-agnostic. Each capability's fragment renders its own+status / lifecycle controls (CONNECT health badge, REFERENCE+enable/disable, etc.).+{% endcomment %}+{% with capability_actions_template=capability_gateway.get_attribute_actions_template_name %}+{% if capability_actions_template %}+{% include capability_actions_template %}{% endif %}+{% endwith %}{% endblock %}{% block file_upload_button %}{% endblock %}diff --git a/src/hi/integrations/templates/integrations/panes/integration_modal_header.html b/src/hi/integrations/templates/integrations/panes/integration_modal_header.htmlnew file mode 100644index 00000000..3ea71775--- /dev/null+++ b/src/hi/integrations/templates/integrations/panes/integration_modal_header.html@@ -0,0 +1,11 @@+{% load static %}+{% if integration_data %}+<div class="d-flex align-items-center mb-3 pb-2 border-bottom">+ <img class="mr-2 hi-integration-logo"+ src="{% static integration_data.integration_metadata.logo_static_path %}"+ alt="{{ integration_data.label }} Logo">+ <div class="text-muted small text-uppercase hi-uppercase-label">+ {{ integration_data.label }}+ </div>+</div>+{% endif %}diff --git a/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.html b/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.htmlnew file mode 100644index 00000000..2c3a0e5c--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/modals/attr_picker.html@@ -0,0 +1,89 @@+{% extends "modals/action_with_cancel.html" %}+{% load icons %}++{% comment %}+ATTRIBUTE_REFERENCE picker modal.++Selection state lives in attr-picker.js (one selection set per open+modal instance, keyed by the picker-root DOM node — i.e., this+modal-dialog). attr-picker.js attaches its handlers as delegated+listeners at document level, so antinode-injected modal content+wires up automatically — no init step in this template.++Layout:++ - Modal dialog gets ``modal-dialog-scrollable`` (Bootstrap-native+ opt-in: the modal-body scrolls, while modal-header and+ modal-footer stay anchored). The selection chip row + Add+ button live in the footer alongside Cancel, so they remain+ visible regardless of how far the operator scrolls through+ search results.+ - The picker-root class lives on the modal-dialog so JS handlers+ can ``closest()`` from either body (search row, result cards)+ or footer (chips, attach form) and find the same picker.++Context:+ integration_data_list : list[IntegrationData]+ integration_data : IntegrationData (initially-selected source)+ item_type_value : str(ItemType.ENTITY) or str(ItemType.LOCATION)+ item_id : int (host record id)+ limit : int (initial page size)+ page_size_choices : tuple[int]++Wire-format strings (DOM class names, data-attribute names, form+field names) come from ``hi.constants.DIVID`` (mirrored in+``static/js/main.js`` under ``Hi.ATTR_PICKER_*``).+{% endcomment %}++{% block modal_dialog_class %}modal-dialog-scrollable hi-modal-dialog-700 {{ DIVID.ATTR_PICKER_ROOT_CLASS }}{% endblock %}++{% block title_text %}+Link Content+{% endblock %}++{% block body %}+{% include "integrations/referencer/panes/attr_picker_body.html" %}+{% endblock %}++{% block footer %}+<div class="w-100">++ {# ----- Chip row + empty-state hint ----- #}+ <div class="d-flex flex-wrap align-items-center mb-2 mt-1">+ <div class="{{ DIVID.ATTR_PICKER_CHIPS_EMPTY_CLASS }} small text-muted">+ No content selected yet.+ </div>+ <div class="{{ DIVID.ATTR_PICKER_CHIPS_CLASS }} d-flex flex-wrap"></div>+ </div>++ {# ----- Cancel + Add row ----- #}+ <div class="d-flex justify-content-between align-items-center">+ <a id="hi-modal-cancel" role="button"+ class="btn btn-outline-tertiary" href="#" data-dismiss="modal">+ {% icon "cancel" size="sm" css_class="hi-icon-left" %}CANCEL+ </a>+ {% comment %}+ No ``data-async`` here: attr-picker.js owns the submit so it can+ populate ``selections_json`` and POST through antinode's public+ API (``AN.hideModalIfNeeded`` + ``AN.post``). Letting antinode+ also bind via ``data-async`` would race the field-population —+ antinode reads the form at the <body> level before attr-picker's+ document-level submit handler fires.+ {% endcomment %}+ <form class="{{ DIVID.ATTR_PICKER_ATTACH_FORM_CLASS }} m-0"+ method="post"+ action="{% url 'integrations_attribute_reference_attach' %}">+ {% csrf_token %}+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_ITEM_TYPE_FIELD }}" value="{{ item_type_value }}">+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_ITEM_ID_FIELD }}" value="{{ item_id }}">+ <input type="hidden" name="{{ DIVID.ATTR_PICKER_SELECTIONS_JSON_FIELD }}" value="">+ <button type="submit"+ class="btn btn-primary {{ DIVID.ATTR_PICKER_ATTACH_BTN_CLASS }}"+ disabled>+ {% icon "check-circle" size="sm" css_class="hi-icon-left" %}<span class="{{ DIVID.ATTR_PICKER_ATTACH_LABEL_CLASS }}">Add 0 Links</span>+ </button>+ </form>+ </div>++</div>+{% endblock %}diff --git a/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.html b/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.htmlnew file mode 100644index 00000000..3516e58c--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/pages/integration_manage.html@@ -0,0 +1,86 @@+{% extends "config/pages/config_base.html" %}+{% load icons static %}++{% block config_content %}+<div id="hi-integration-settings" class="d-flex">+ <nav class="nav flex-column hi-vertical-nav">+ <div class="hi-vertical-nav-header">+ <span class="d-flex align-items-center justify-content-center w-100 font-weight-bold text-muted py-2"+ style="white-space: nowrap;">+ {% icon "collection" size="sm" css_class="hi-icon-left" %}CONTENT SOURCES+ </span>+ </div>+ {% for item in core.integration_data_list %}+ <a class="nav-link hi-vertical-nav-link {% if core.integration_data.integration_id == item.integration_id %}active{% endif %}"+ href="{% url 'integrations_reference_manage' integration_id=item.integration_id %}"+ data-async="true">+ <div class="d-flex justify-content-between align-items-center">+ <span class="d-flex align-items-center" style="white-space: nowrap;">+ <img src="{% static item.integration_metadata.logo_static_path %}"+ alt="{{ item.label }}"+ style="max-height: 18px; width: auto; margin-right: 6px; flex-shrink: 0;">+ {{ item.label }}+ </span>+ </div>+ </a>+ {% endfor %}+ </nav>+ <div class="flex-column flex-grow-1" style="min-width: 0;">+ <div class="tab-content m-3">++ <div id="{{ attr_item_context.container_html_id }}"+ class="{{ DIVID.ATTR_V2_CONTAINER_CLASS }}" >++ <div class="border-bottom mb-2 pb-2">+ <div class="d-flex justify-content-between">+ <div class="h3 integration-title mb-0">+ <img class="img-fluid"+ src="{% static core.integration_data.integration_metadata.logo_static_path %}"+ alt="{{ core.integration_data.integration_metadata.label }} Logo">+ {{ core.integration_data.integration_metadata.label }}+ </div>+ </div>+ <div class="text-muted small mt-1">+ Find related content in {{ core.integration_data.integration_metadata.label }} and link to it.+ </div>+ </div>++ <div class="{{ DIVID.ATTR_V2_FORM_CLASS }}">+ <form id="{{ attr_item_context.form_html_id }}"+ action="{% url 'integrations_reference_manage' integration_id=core.integration_data.integration_id %}"+ method="post"+ class="{{ DIVID.ATTR_V2_FORM_CLASS }} form"+ enctype="multipart/form-data">+ {% csrf_token %}++ <div id="{{ attr_item_context.content_html_id }}"+ class="{{ DIVID.ATTR_V2_CONTENT_CLASS }}">+ {% include "integrations/panes/integration_edit_content_body.html" %}+ </div>+ </form>+ </div>++ {% if messages %}+ <div class="{{ DIVID.ATTR_V2_MESSAGES }}" id="{{ DIVID.ATTR_V2_MESSAGES }}">+ {% for message in messages %}+ <div class="alert alert-{{ message.tags }} alert-dismissible fade show" role="alert">+ {{ message }}+ <button type="button" class="close" data-dismiss="alert" aria-label="Close">+ <span aria-hidden="true">×</span>+ </button>+ </div>+ {% endfor %}+ </div>+ {% endif %}+ </div>++ </div>+ </div>+</div>++<script>+ if (window.Hi && window.Hi.attr && window.Hi.attr.initializeContainer) {+ window.Hi.attr.initializeContainer('#{{ attr_item_context.container_html_id }}');+ }+</script>+{% endblock %}diff --git a/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.html b/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.htmlnew file mode 100644index 00000000..ea7b528f--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/pages/no_integrations.html@@ -0,0 +1,6 @@+{% extends "config/pages/config_base.html" %}+{% block config_content %}+<div class="alert alert-info text-center m-4">+ No content sources are installed.+</div>+{% endblock %}diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.html b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.htmlnew file mode 100644index 00000000..bead3e1c--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_body.html@@ -0,0 +1,115 @@+{% load icons static %}+{% comment %}+Picker modal body. Holds the search controls and a placeholder+container for result cards (server-rendered partial swapped in on+each search by attr-picker.js).++The chip row, Cancel button, and Add button live in the modal+footer (see attr_picker.html). The footer stays anchored when the+body scrolls because the modal opts into Bootstrap's+``modal-dialog-scrollable`` behavior.++The picker-root class lives on the modal-dialog, not on this body,+so JS handlers in both body and footer can ``closest()`` to the+same picker instance.++DOM classes, data-attribute names, and wire-format field names+come from ``hi.constants.DIVID`` (mirrored in ``static/js/main.js``+under ``Hi.ATTR_PICKER_*``).++Context:+ integration_data_list : list[IntegrationData]+ integration_data : IntegrationData (the default-selected source)+ item_type_value : str (ItemType serialized)+ item_id : int+ limit : int (initial page size)+ page_size_choices : tuple[int]+{% endcomment %}++{# ----- Search form ----- #}+<form class="{{ DIVID.ATTR_PICKER_SEARCH_FORM_CLASS }}"+ {{ DIVID.ATTR_PICKER_SEARCH_URL_ATTR }}="{% url 'integrations_attribute_reference_search' %}">+ {% csrf_token %}++ {% comment %}+ Source banner: always rendered so the UI shape is identical+ whether one source or many. Bootstrap dropdown shows+ ``[logo] [name] [caret]``; the caret + dropdown are disabled+ via CSS when only one source is configured. The current source+ is carried in a sibling hidden input that attr-picker.js+ updates on dropdown selection.+ {% endcomment %}+ <div class="dropdown mb-3+ {% if integration_data_list|length == 1 %}hi-attr-picker-source-banner-single{% endif %}">+ <button type="button"+ class="btn btn-light btn-block dropdown-toggle text-left d-flex align-items-center {{ DIVID.ATTR_PICKER_SOURCE_BANNER_CLASS }}"+ data-toggle="dropdown"+ aria-haspopup="true"+ aria-expanded="false"+ {% if integration_data_list|length == 1 %}disabled{% endif %}>+ <img class="mr-2 {{ DIVID.ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS }}"+ src="{% static integration_data.integration_metadata.logo_static_path %}"+ alt="">+ <span class="flex-grow-1 {{ DIVID.ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS }}">+ {{ integration_data.label }}+ </span>+ </button>+ <div class="dropdown-menu w-100">+ {% for option in integration_data_list %}+ <a href="#"+ class="dropdown-item d-flex align-items-center {{ DIVID.ATTR_PICKER_SOURCE_OPTION_CLASS }}"+ {{ DIVID.ATTR_PICKER_SOURCE_ID_ATTR }}="{{ option.integration_id }}"+ {{ DIVID.ATTR_PICKER_SOURCE_LOGO_ATTR }}="{% static option.integration_metadata.logo_static_path %}"+ {{ DIVID.ATTR_PICKER_SOURCE_LABEL_ATTR }}="{{ option.label }}">+ <img class="mr-2" src="{% static option.integration_metadata.logo_static_path %}" alt="">+ <span>{{ option.label }}</span>+ </a>+ {% endfor %}+ </div>+ </div>+ <input type="hidden"+ name="{{ DIVID.ATTR_PICKER_INTEGRATION_ID_FIELD }}"+ value="{{ integration_data.integration_id }}">++ <div class="form-row align-items-end mb-3">+ <div class="col">+ <label for="hi-attr-picker-query" class="small text-muted mb-1">+ Search+ </label>+ <input type="text"+ id="hi-attr-picker-query"+ name="{{ DIVID.ATTR_PICKER_QUERY_FIELD }}"+ value="{{ query }}"+ placeholder="Type to search and press Enter"+ class="form-control form-control-sm"+ autofocus>+ </div>+ <div class="col-auto">+ <label for="hi-attr-picker-limit" class="small text-muted mb-1">+ Page size+ </label>+ <select id="hi-attr-picker-limit"+ name="{{ DIVID.ATTR_PICKER_LIMIT_FIELD }}"+ class="form-control form-control-sm">+ {% for choice in page_size_choices %}+ <option value="{{ choice }}" {% if choice == limit %}selected{% endif %}>{{ choice }}</option>+ {% endfor %}+ </select>+ </div>+ <div class="col-auto">+ <button type="submit" class="btn btn-sm btn-outline-primary">+ {% icon "zoom" size="sm" css_class="hi-icon-left" %}Search+ </button>+ </div>+ </div>+</form>++{# ----- Results container ----- #}+{% comment %}+The initial render uses the same partial the search endpoint+returns; attr-picker.js swaps the container's contents on each+subsequent search.+{% endcomment %}+<div class="{{ DIVID.ATTR_PICKER_RESULTS_CLASS }}">+ {% include "integrations/referencer/panes/attr_picker_results.html" %}+</div>diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.html b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.htmlnew file mode 100644index 00000000..56187c13--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/panes/attr_picker_results.html@@ -0,0 +1,52 @@+{% load icons %}+{% comment %}+Result-cards partial returned by the search endpoint and swapped+into the picker's results container by attr-picker.js. Each card+carries the source title and URL as data attributes so the JS can+read them on checkbox change without parsing the DOM.++DOM classes / data-attribute names come from ``hi.constants.DIVID``+(mirrored in ``static/js/main.js`` under ``Hi.ATTR_PICKER_*``).++Context:+ query : str (the search query that produced these results;+ used only for the no-results message)+ results : list[AttributeReferenceResult]+{% endcomment %}+{% if query and not results %}+<div class="text-muted small">No results.</div>+{% endif %}+{% if results %}+<div class="list-group">+ {% for r in results %}+ <label class="list-group-item d-flex align-items-start mb-0">+ <input type="checkbox"+ class="{{ DIVID.ATTR_PICKER_RESULT_CHECKBOX_CLASS }} mt-1 mr-3"+ {{ DIVID.ATTR_PICKER_TITLE_ATTR }}="{{ r.title }}"+ {{ DIVID.ATTR_PICKER_SOURCE_URL_ATTR }}="{{ r.source_url }}">+ {% if r.thumbnail_url %}+ <img src="{{ r.thumbnail_url }}"+ alt=""+ class="mr-3 rounded"+ style="width: 56px; height: 56px; object-fit: cover;">+ {% else %}+ <div class="mr-3 d-flex align-items-center justify-content-center bg-light rounded text-muted"+ style="width: 56px; height: 56px;">+ {% icon "info-circle" size="sm" %}+ </div>+ {% endif %}+ <div class="flex-grow-1" style="min-width: 0;">+ <div class="font-weight-bold text-truncate">{{ r.title }}</div>+ {% if r.snippet %}+ <div class="small text-muted text-truncate">{{ r.snippet }}</div>+ {% endif %}+ <a href="{{ r.source_url }}" target="_blank" rel="noopener"+ class="small text-truncate d-block"+ onclick="event.stopPropagation();">+ {{ r.source_url }}+ </a>+ </div>+ </label>+ {% endfor %}+</div>+{% endif %}diff --git a/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.html b/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.htmlnew file mode 100644index 00000000..17bb94ae--- /dev/null+++ b/src/hi/integrations/templates/integrations/referencer/panes/attribute_actions.html@@ -0,0 +1,33 @@+{% load icons %}+{% comment %}+Attribute-form action-bar fragment for the ATTRIBUTE_REFERENCE+capability: ENABLED / DISABLED status badge plus the DISABLE+button (only when enabled). The framework re-renders this+fragment as part of the attribute form's post-save response, so+the badge and button update in place on every successful save.++Context (inherited from the surrounding edit body):+ integration_data : IntegrationData (required)+{% endcomment %}+{% if integration_data.integration.is_enabled %}+<span class="badge badge-success ml-3 px-2 py-1 align-self-center">+ {% icon "check-circle" size="sm" css_class="hi-icon-left" %}ENABLED+</span>+{% comment %}+DISABLE shares the surrounding attribute form (HTML forbids nested+forms; the attr.js wiring reads the outer form's ``action`` and+ignores ``formaction``). Dispatch is via the ``action`` POST field+— the manage view's POST handler branches on it.+{% endcomment %}+<button type="submit"+ name="action"+ value="disable"+ formnovalidate+ class="btn btn-outline-danger ml-2">+ {% icon "close" size="sm" css_class="hi-icon-left" %}DISABLE+</button>+{% else %}+<span class="badge badge-secondary ml-3 px-2 py-1 align-self-center">+ {% icon "info-circle" size="sm" css_class="hi-icon-left" %}DISABLED+</span>+{% endif %}diff --git a/src/hi/integrations/templatetags/integration_tags.py b/src/hi/integrations/templatetags/integration_tags.pyindex 8b4b3887..6b68c3ad 100644--- a/src/hi/integrations/templatetags/integration_tags.py+++ b/src/hi/integrations/templatetags/integration_tags.py@@ -1,6 +1,7 @@import loggingfrom django import template+from hi.integrations.enums import IntegrationCapabilityfrom hi.integrations.models import IntegrationDetailsModelfrom hi.integrations.integration_manager import IntegrationManager@@ -65,6 +66,17 @@ def previous_integration_logo_path( model : IntegrationDetailsModel ) -> str:return metadata.logo_static_path if metadata else ''+def has_attribute_referencers() -> bool:+ """True iff at least one currently-enabled integration advertises+ the ATTRIBUTE_REFERENCE capability. Used by Entity/Location edit+ surfaces to decide whether to show the "LINK" action-bar button."""+ return bool( IntegrationManager().get_integration_data_list(+ enabled_only = True,+ capabilities = frozenset({ IntegrationCapability.ATTRIBUTE_REFERENCE }),+ ) )++@register.inclusion_tag( 'integrations/connector/panes/integration_health_banner.html' )def integration_health_banner( integration_id : str, context_message : str = None ):"""Render a banner when the integration is in a non-healthy state.diff --git a/src/hi/integrations/tests/test_importer_views.py b/src/hi/integrations/tests/test_importer_views.pyindex 6f8cd07d..3ba60ac4 100644--- a/src/hi/integrations/tests/test_importer_views.py+++ b/src/hi/integrations/tests/test_importer_views.py@@ -162,7 +162,7 @@ class DataImportPageViewTests(TestCase):)),])response = self.client.get(reverse('integrations_import_home'))- self.assertIn('Also available as an', response.content.decode())+ self.assertIn('Also available as a Connector', response.content.decode())class ImporterConfigureViewTests(TestCase):@@ -256,7 +256,7 @@ class ImporterConfigureViewTests(TestCase):response = self.client.get(self._url())body = response.content.decode()self.assertIn('Cannot configure', body)- self.assertIn('GO TO INTEGRATIONS', body)+ self.assertIn('GO TO CONNECTORS', body)self.assertIn(reverse('integrations_connect_home'), body)def test_get_import_not_blocked_for_single_capability_integration(self):diff --git a/src/hi/integrations/tests/test_integration_attribute_edit_context.py b/src/hi/integrations/tests/test_integration_attribute_edit_context.pyindex c54f7d12..6eb5335f 100644--- a/src/hi/integrations/tests/test_integration_attribute_edit_context.py+++ b/src/hi/integrations/tests/test_integration_attribute_edit_context.py@@ -7,6 +7,8 @@ import loggingfrom django.test import TestCasefrom hi.apps.attribute.enums import AttributeValueType+from hi.integrations.connector.integration_connector import IntegrationConnector+from hi.integrations.importer.integration_importer import IntegrationImporterfrom hi.integrations.integration_attribute_edit_context import (IntegrationAttributeItemEditContext,)@@ -85,10 +87,10 @@ class CapabilityFilteredFormsetTests(TestCase):integration=self.integration,)- def _attribute_names_for(self, capability):+ def _attribute_names_for(self, capability_gateway):edit_context = IntegrationAttributeItemEditContext(integration_data=self.integration_data,- capability=capability,+ capability_gateway=capability_gateway,)return sorted(attr.integration_key.integration_name@@ -97,12 +99,12 @@ class CapabilityFilteredFormsetTests(TestCase):def test_connect_context_excludes_import_only(self):self.assertEqual(- self._attribute_names_for(IntegrationCapability.CONNECT),+ self._attribute_names_for(IntegrationConnector()),['connect_field', 'shared_field'],)def test_import_context_excludes_connect_only(self):self.assertEqual(- self._attribute_names_for(IntegrationCapability.IMPORT),+ self._attribute_names_for(IntegrationImporter()),['import_field', 'shared_field'],)diff --git a/src/hi/integrations/tests/test_integration_connector.py b/src/hi/integrations/tests/test_integration_connector.pyindex cdad2d96..b5ec4bce 100644--- a/src/hi/integrations/tests/test_integration_connector.py+++ b/src/hi/integrations/tests/test_integration_connector.py@@ -48,7 +48,7 @@ class TestSynchronizer(IntegrationConnector):abstract hooks so the class can be instantiated; sync() itselfis not exercised here."""- def get_integration_metadata(self):+ def get_metadata(self):return _stub_integration_metadata()def get_result_title(self, is_initial_connect=False):@@ -1254,7 +1254,7 @@ class ReconnectDisconnectedItemsFrameworkTests(TestCase):integration_label = self.INTEGRATION_LABELclass RecordingSynchronizer(IntegrationConnector):- def get_integration_metadata(self):+ def get_metadata(self):return _stub_integration_metadata(integration_id=integration_id,label=integration_label,@@ -1361,7 +1361,7 @@ class ReconnectDisconnectedItemsFrameworkTests(TestCase):# _rebuild_integration_components hook (the missing# override under test) rather than tripping on the# earlier metadata abstract-hook check.- def get_integration_metadata(_self):+ def get_metadata(_self):return _stub_integration_metadata(integration_id=self.INTEGRATION_ID,label=self.INTEGRATION_LABEL,@@ -1417,7 +1417,7 @@ class IntegrationConnectorReconnectCycleTests(TestCase):integration_label = self.INTEGRATION_LABELclass TestE2ESynchronizer(IntegrationConnector):- def get_integration_metadata(self):+ def get_metadata(self):return _stub_integration_metadata(integration_id=integration_id,label=integration_label,diff --git a/src/hi/integrations/tests/test_reference_manage_views.py b/src/hi/integrations/tests/test_reference_manage_views.pynew file mode 100644index 00000000..91e43eb3--- /dev/null+++ b/src/hi/integrations/tests/test_reference_manage_views.py@@ -0,0 +1,293 @@+"""View tests for the Content Sources management page.++Covers the GET-render, the Save/Enable submission flow (validate ++save + flip ``is_enabled`` on first activation), and the Disable+endpoint (flip ``is_enabled`` to False, credentials preserved).+"""+import logging++from django.urls import reverse++from hi.apps.attribute.enums import AttributeType, AttributeValueType+from hi.integrations.integration_data import IntegrationData+from hi.integrations.integration_manager import IntegrationManager+from hi.integrations.models import Integration, IntegrationAttribute+from hi.integrations.transient_models import (+ ConnectionTestResult,+ IntegrationKey,+)+from hi.services.paperless.enums import PlAttributeType+from hi.services.paperless.integration import PaperlessGateway+from hi.services.paperless.pl_metadata import PaperlessMetaData+from hi.testing.view_test_base import ViewTestBase+++logging.disable(logging.CRITICAL)+++def _seed_manager( *integration_data ):+ """Seed the IntegrationManager singleton's in-memory data map.+ The manager is singletoned across the test process, so this+ explicit seed is the supported way for view tests to inject the+ integration data the views look up."""+ manager = IntegrationManager()+ manager._integration_data_map = {+ data.integration_id: data for data in integration_data+ }+++def _make_attr( integration, attr_type, value ):+ attr = IntegrationAttribute.objects.create(+ integration = integration,+ name = attr_type.label,+ value = value,+ value_type_str = str(AttributeValueType.TEXT),+ attribute_type_str = str(AttributeType.PREDEFINED),+ is_editable = attr_type.is_editable,+ is_required = attr_type.is_required,+ )+ attr.integration_key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str(attr_type),+ )+ attr.save()+ return attr+++class TestReferenceManageGet( ViewTestBase ):++ def setUp(self):+ super().setUp()+ self.client.force_login(self.user)+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = False,+ )+ _seed_manager(IntegrationData(+ integration_gateway = PaperlessGateway(),+ integration = self.integration,+ ))++ def _url(self):+ return reverse(+ 'integrations_reference_manage',+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },+ )++ def test_renders_with_disabled_status(self):+ response = self.client.get(self._url())+ self.assertEqual(response.status_code, 200)+ body = response.content.decode()+ self.assertIn('Paperless-ngx', body)+ # Disabled-state hallmarks: badge + ENABLE button label.+ self.assertIn('DISABLED', body)+ self.assertIn('ENABLE', body)+ # No DISABLE button rendered when already disabled.+ self.assertNotIn('integrations_reference_deactivate', body)++ def test_renders_with_enabled_status(self):+ self.integration.is_enabled = True+ self.integration.save()+ response = self.client.get(self._url())+ self.assertEqual(response.status_code, 200)+ body = response.content.decode()+ self.assertIn('ENABLED', body)+ # When enabled, the form button reverts to UPDATE and the+ # DISABLE button is wired in the header.+ self.assertIn('UPDATE', body)+ self.assertIn('DISABLE', body)+++class TestReferenceManagePost( ViewTestBase ):++ def setUp(self):+ super().setUp()+ self.client.force_login(self.user)+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = False,+ )+ _seed_manager(IntegrationData(+ integration_gateway = PaperlessGateway(),+ integration = self.integration,+ ))+ # Required-by-framework predefined attribute rows. The+ # formset edits these in place rather than creating new+ # rows on submit.+ self.url_attr = _make_attr(self.integration, PlAttributeType.API_URL, '')+ self.token_attr = _make_attr(self.integration, PlAttributeType.API_TOKEN, '')++ def _url(self):+ return reverse(+ 'integrations_reference_manage',+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },+ )++ def _form_payload(self, api_url, api_token):+ # Formset wire shape: prefix is f'{owner_type}-{owner.id}'+ # (see ``AttributeItemEditContext.formset_prefix``). The+ # inline IntegrationAttribute formset wraps existing rows+ # by id; we re-post each row's name + value to keep the+ # formset valid.+ prefix = f'integration-{self.integration.id}'+ return {+ f'{prefix}-TOTAL_FORMS': '2',+ f'{prefix}-INITIAL_FORMS': '2',+ f'{prefix}-MIN_NUM_FORMS': '0',+ f'{prefix}-MAX_NUM_FORMS': '100',++ f'{prefix}-0-id': str(self.url_attr.id),+ f'{prefix}-0-name': self.url_attr.name,+ f'{prefix}-0-value': api_url,++ f'{prefix}-1-id': str(self.token_attr.id),+ f'{prefix}-1-name': self.token_attr.name,+ f'{prefix}-1-value': api_token,+ }++ def _patch_validate_access(self, success: bool, message: str = ''):+ from unittest.mock import patch+ result = (+ ConnectionTestResult.success() if success+ else ConnectionTestResult.failure(message or 'probe failed')+ )+ return patch(+ 'hi.services.paperless.integration.PaperlessGateway.validate_access',+ return_value = result,+ )++ def test_save_with_valid_creds_enables_disabled_integration(self):+ with self._patch_validate_access(success = True):+ response = self.client.post(self._url(), data = self._form_payload(+ api_url = 'https://paperless.example.com/',+ api_token = 'good-token',+ ))++ self.integration.refresh_from_db()+ self.url_attr.refresh_from_db()+ self.token_attr.refresh_from_db()+ self.assertEqual(response.status_code, 200)+ self.assertTrue(self.integration.is_enabled)+ self.assertEqual(self.url_attr.value, 'https://paperless.example.com/')+ self.assertEqual(self.token_attr.value, 'good-token')++ def test_save_on_already_enabled_keeps_enabled(self):+ # UPDATE flow: integration is enabled; save should keep+ # is_enabled=True and persist any credential changes.+ self.integration.is_enabled = True+ self.integration.save()+ self.url_attr.value = 'https://old.example.com/'+ self.url_attr.save()++ with self._patch_validate_access(success = True):+ response = self.client.post(self._url(), data = self._form_payload(+ api_url = 'https://new.example.com/',+ api_token = 'rotated-token',+ ))++ self.integration.refresh_from_db()+ self.url_attr.refresh_from_db()+ self.assertEqual(response.status_code, 200)+ self.assertTrue(self.integration.is_enabled)+ self.assertEqual(self.url_attr.value, 'https://new.example.com/')++ def test_save_with_bad_access_does_not_save_or_enable(self):+ # Atomic semantics: failed probe blocks the save entirely.+ # Neither attributes nor is_enabled change. Operator sees+ # the access failure inline on the form (framework error+ # response renders the form again with errors).+ self.url_attr.value = 'https://old.example.com/'+ self.url_attr.save()++ with self._patch_validate_access(+ success = False, message = 'auth rejected',+ ):+ response = self.client.post(self._url(), data = self._form_payload(+ api_url = 'https://new.example.com/',+ api_token = 'bad-token',+ ))++ self.integration.refresh_from_db()+ self.url_attr.refresh_from_db()+ # Framework returns 400 on form errors (the antinode+ # response carries the re-rendered form for swap-in).+ self.assertEqual(response.status_code, 400)+ self.assertFalse(self.integration.is_enabled)+ self.assertEqual(self.url_attr.value, 'https://old.example.com/')++ def test_save_with_bad_access_when_enabled_keeps_old_state(self):+ # The (a) post-condition: an UPDATE-while-enabled with a bad+ # probe leaves the integration enabled with its previously+ # working creds. Nothing partially changes.+ self.integration.is_enabled = True+ self.integration.save()+ self.url_attr.value = 'https://old.example.com/'+ self.url_attr.save()++ with self._patch_validate_access(+ success = False, message = 'auth rejected',+ ):+ response = self.client.post(self._url(), data = self._form_payload(+ api_url = 'https://new.example.com/',+ api_token = 'rotated-token',+ ))++ self.integration.refresh_from_db()+ self.url_attr.refresh_from_db()+ self.assertEqual(response.status_code, 400)+ # Still enabled, still old URL.+ self.assertTrue(self.integration.is_enabled)+ self.assertEqual(self.url_attr.value, 'https://old.example.com/')+++class TestReferenceDisableAction( ViewTestBase ):+ """Disable rides the manage URL as an in-form action — the+ DISABLE button submits the surrounding attribute form with+ ``action=disable`` in the POST body, which the view dispatches+ on. No separate URL."""++ def setUp(self):+ super().setUp()+ self.client.force_login(self.user)+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = True,+ )+ _seed_manager(IntegrationData(+ integration_gateway = PaperlessGateway(),+ integration = self.integration,+ ))++ def _url(self):+ return reverse(+ 'integrations_reference_manage',+ kwargs = { 'integration_id': PaperlessMetaData.integration_id },+ )++ def test_disable_action_flips_is_enabled(self):+ response = self.client.post(self._url(), data = { 'action': 'disable' })+ self.assertEqual(response.status_code, 200)+ self.integration.refresh_from_db()+ self.assertFalse(self.integration.is_enabled)++ def test_disable_action_already_disabled_is_no_op(self):+ self.integration.is_enabled = False+ self.integration.save()+ response = self.client.post(self._url(), data = { 'action': 'disable' })+ self.assertEqual(response.status_code, 200)+ self.integration.refresh_from_db()+ self.assertFalse(self.integration.is_enabled)++ def test_disable_action_skips_credential_validation(self):+ # Disable bypasses the access probe — operators must be able+ # to disable a misconfigured integration without first+ # fixing the credentials.+ from unittest.mock import patch+ with patch(+ 'hi.services.paperless.integration.PaperlessGateway.validate_access',+ ) as mock_probe:+ response = self.client.post(self._url(), data = { 'action': 'disable' })+ self.assertEqual(response.status_code, 200)+ mock_probe.assert_not_called()+ self.integration.refresh_from_db()+ self.assertFalse(self.integration.is_enabled)diff --git a/src/hi/integrations/tests/test_referencer_views.py b/src/hi/integrations/tests/test_referencer_views.pynew file mode 100644index 00000000..d3a89e46--- /dev/null+++ b/src/hi/integrations/tests/test_referencer_views.py@@ -0,0 +1,534 @@+"""View tests for the ATTRIBUTE_REFERENCE picker.++The picker is split into three endpoints:++ - ``integrations_attribute_reference_picker`` — GET, renders the+ initial empty modal.+ - ``integrations_attribute_reference_search`` — POST, returns the+ result-cards partial. The attr-picker.js module swaps the+ returned HTML into the picker's results container.+ - ``integrations_attribute_reference_attach`` — POST, reads the+ JS-built ``selections_json`` payload, creates one TEXT+ attribute per record, returns ``antinode.refresh_response()``.++Selection state lives in JS during the session; the server is+consulted only at search time (per-query) and at attach time (the+single final commit).+"""+import json+import logging++from django.urls import reverse++from hi.apps.attribute.enums import AttributeType, AttributeValueType+from hi.apps.entity.enums import EntityType+from hi.apps.entity.models import Entity, EntityAttribute+from hi.apps.location.models import Location, LocationAttribute+from hi.enums import ItemType, ViewMode+from hi.integrations.enums import IntegrationAttributeType, IntegrationCapability+from hi.integrations.integration_data import IntegrationData+from hi.integrations.integration_gateway import IntegrationGateway+from hi.integrations.integration_manager import IntegrationManager+from hi.integrations.models import Integration+from hi.integrations.referencer.integration_referencer import (+ IntegrationAttributeReferencer,+)+from hi.constants import DIVID+from hi.integrations.referencer.transient_models import (+ AttributeReferenceResult,+)+from hi.integrations.transient_models import (+ ConnectionTestResult,+ IntegrationMetaData,+ IntegrationValidationResult,+)+from hi.testing.view_test_base import ViewTestBase+++logging.disable(logging.CRITICAL)+++# ---- fixtures ----------------------------------------------------+++class _RefAttributeType(IntegrationAttributeType):+ TEST_ATTR = (+ 'Test Attr', '',+ AttributeValueType.TEXT, {}, True, True, 'default',+ )+++class _StubReferencer(IntegrationAttributeReferencer):+ """In-memory referencer the tests inject via the gateway.+ Captures search args so tests can assert dispatch shape."""++ def __init__(self, integration_id='ref', label='Ref Test',+ results=None, raises=None):+ self._integration_id = integration_id+ self._label = label+ self._results = results or []+ self._raises = raises+ self.last_query = None+ self.last_limit = None++ def get_metadata(self):+ return IntegrationMetaData(+ integration_id=self._integration_id,+ label=self._label,+ attribute_type=_RefAttributeType,+ allow_entity_deletion=True,+ capabilities=frozenset({IntegrationCapability.ATTRIBUTE_REFERENCE}),+ )++ def validate_configuration(self, integration_attributes):+ return IntegrationValidationResult.success()++ def search_references(self, query, limit=20):+ self.last_query = query+ self.last_limit = limit+ if self._raises is not None:+ raise self._raises+ return list(self._results)+++class _ReferencerCapableGateway(IntegrationGateway):+ """Gateway that advertises ATTRIBUTE_REFERENCE and returns the+ test's stub referencer from ``get_attribute_referencer``."""++ def __init__(self, integration_id='ref', label='Ref Test', referencer=None):+ self.integration_id = integration_id+ self.label = label+ self._referencer = referencer++ def get_metadata(self):+ return IntegrationMetaData(+ integration_id=self.integration_id,+ label=self.label,+ attribute_type=_RefAttributeType,+ allow_entity_deletion=True,+ capabilities=frozenset({IntegrationCapability.ATTRIBUTE_REFERENCE}),+ )++ def validate_configuration(self, integration_attributes):+ return IntegrationValidationResult.success()++ def validate_access(self, integration_attributes, timeout_secs):+ return ConnectionTestResult.success()++ def get_attribute_referencer(self):+ return self._referencer+++def _populate_manager(pairs, enabled=True):+ """Seed the IntegrationManager with the given (id, gateway) pairs.+ By default the integrations are marked enabled so the picker view+ sees them through its ``enabled_only=True`` filter."""+ manager = IntegrationManager()+ manager._integration_data_map = {}+ for integration_id, gateway in pairs:+ integration, _ = Integration.objects.get_or_create(+ integration_id=integration_id,+ defaults={'is_enabled': enabled},+ )+ if integration.is_enabled != enabled:+ integration.is_enabled = enabled+ integration.save()+ manager._integration_data_map[integration_id] = IntegrationData(+ integration_gateway=gateway,+ integration=integration,+ )+++def _result(title='Doc', source_url='https://example.com/doc/1',+ thumbnail_url=None, mime_type=None, snippet=None):+ return AttributeReferenceResult(+ title=title,+ source_url=source_url,+ thumbnail_url=thumbnail_url,+ mime_type=mime_type,+ snippet=snippet,+ )+++# ---- gateway default --------------------------------------------+++class TestIntegrationGatewayAttributeReferencerDefault(ViewTestBase):+ """Default ``IntegrationGateway`` advertises no ATTRIBUTE_REFERENCE+ referencer — only integrations that explicitly opt in do."""++ def test_default_returns_none(self):+ self.assertIsNone(IntegrationGateway().get_attribute_referencer())+++# ---- picker GET ----------------------------------------------------+++class TestAttributeReferencePickerView(ViewTestBase):+ """GET renders the initial empty modal. Search and attach are+ sibling endpoints (tested separately below)."""++ INTEGRATION_ID = 'ref'++ def setUp(self):+ super().setUp()+ IntegrationManager()._instances = {}+ IntegrationManager._initialized_instance = None+ self.client.force_login(self.user)+ self.setSessionViewMode(ViewMode.EDIT)+ self.referencer = _StubReferencer(integration_id=self.INTEGRATION_ID)+ self.gateway = _ReferencerCapableGateway(+ self.INTEGRATION_ID, referencer=self.referencer,+ )+ _populate_manager([(self.INTEGRATION_ID, self.gateway)])++ def _entity(self, name='Dishwasher'):+ return Entity.objects.create(+ name=name,+ entity_type_str=str(EntityType.DISHWASHER),+ )++ def _url(self):+ return reverse('integrations_attribute_reference_picker')++ def test_get_renders_modal_with_integration_label(self):+ entity = self._entity()+ response = self.client.get(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertIn('Ref Test', response.content.decode())++ def test_get_with_no_enabled_referencer_returns_404(self):+ _populate_manager([])+ entity = self._entity()+ response = self.client.get(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 404)++ def test_get_unknown_item_type_returns_400(self):+ response = self.client.get(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: 'banana',+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 1,+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 400)++ def test_get_missing_owner_returns_404(self):+ response = self.client.get(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 99999,+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 404)++ def test_get_with_multiple_referencers_renders_selector(self):+ other_ref = _StubReferencer(integration_id='other', label='Other Ref')+ other_gw = _ReferencerCapableGateway(+ 'other', label='Other Ref', referencer=other_ref,+ )+ _populate_manager([+ (self.INTEGRATION_ID, self.gateway),+ ('other', other_gw),+ ])+ entity = self._entity()+ response = self.client.get(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: entity.id,+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ decoded = response.content.decode()+ self.assertIn('Ref Test', decoded)+ self.assertIn('Other Ref', decoded)+++# ---- search endpoint ----------------------------------------------+++class TestAttributeReferenceSearchView(ViewTestBase):+ """POST returns the result-cards partial. The picker JS swaps+ the returned HTML into the results container."""++ INTEGRATION_ID = 'ref'++ def setUp(self):+ super().setUp()+ IntegrationManager()._instances = {}+ IntegrationManager._initialized_instance = None+ self.client.force_login(self.user)+ self.setSessionViewMode(ViewMode.EDIT)+ self.referencer = _StubReferencer(integration_id=self.INTEGRATION_ID)+ self.gateway = _ReferencerCapableGateway(+ self.INTEGRATION_ID, referencer=self.referencer,+ )+ _populate_manager([(self.INTEGRATION_ID, self.gateway)])++ def _url(self):+ return reverse('integrations_attribute_reference_search')++ def _payload(self, query='', limit=20, integration_id=None):+ return {+ DIVID['ATTR_PICKER_QUERY_FIELD']: query,+ DIVID['ATTR_PICKER_LIMIT_FIELD']: str(limit),+ DIVID['ATTR_PICKER_INTEGRATION_ID_FIELD']: integration_id or self.INTEGRATION_ID,+ }++ def test_empty_query_does_not_call_referencer(self):+ response = self.client.post(+ self._url(),+ data=self._payload(query=' '),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertIsNone(self.referencer.last_query)++ def test_search_dispatches_with_clamped_limit(self):+ self.referencer._results = [_result()]+ response = self.client.post(+ self._url(),+ data=self._payload(query='dishwasher', limit=50),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertEqual(self.referencer.last_query, 'dishwasher')+ self.assertEqual(self.referencer.last_limit, 50)++ def test_search_returns_result_cards_html(self):+ self.referencer._results = [+ _result(title='Warranty', source_url='https://p/doc/1'),+ _result(title='Manual', source_url='https://p/doc/2'),+ ]+ response = self.client.post(+ self._url(),+ data=self._payload(query='dishwasher'),+ **self.async_http_headers,+ )+ body = response.content.decode()+ self.assertIn('Warranty', body)+ self.assertIn('Manual', body)+ self.assertIn('https://p/doc/1', body)+ # Cards carry data attributes so JS can read title + URL on+ # checkbox change without parsing the DOM.+ self.assertIn('data-attr-picker-source-url', body)+ self.assertIn('data-attr-picker-title', body)++ def test_search_with_no_results_returns_empty_message(self):+ self.referencer._results = []+ response = self.client.post(+ self._url(),+ data=self._payload(query='nothing-matches'),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertIn('No results', response.content.decode())++ def test_search_invalid_limit_falls_back_to_default(self):+ self.referencer._results = [_result()]+ payload = self._payload(query='q')+ payload[DIVID['ATTR_PICKER_LIMIT_FIELD']] = 'not-a-number'+ self.client.post(+ self._url(), data=payload, **self.async_http_headers,+ )+ self.assertEqual(self.referencer.last_limit, 20)++ def test_search_unknown_integration_id_returns_400(self):+ response = self.client.post(+ self._url(),+ data=self._payload(query='q', integration_id='nope'),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 400)++ def test_search_referencer_exception_yields_empty_results(self):+ self.referencer._raises = RuntimeError('upstream down')+ response = self.client.post(+ self._url(),+ data=self._payload(query='q'),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ # Failure path renders the no-results message rather than+ # surfacing a 5xx — the picker stays usable.+ self.assertIn('No results', response.content.decode())+++# ---- attach endpoint ----------------------------------------------+++class TestAttributeReferenceAttachView(ViewTestBase):+ """POST reads the JS-built ``selections_json`` payload and+ creates one TEXT attribute per record on the named owner."""++ def setUp(self):+ super().setUp()+ IntegrationManager()._instances = {}+ IntegrationManager._initialized_instance = None+ self.client.force_login(self.user)+ self.setSessionViewMode(ViewMode.EDIT)++ def _url(self):+ return reverse('integrations_attribute_reference_attach')++ @staticmethod+ def _entity(name='Dishwasher'):+ return Entity.objects.create(+ name=name,+ entity_type_str=str(EntityType.DISHWASHER),+ )++ @staticmethod+ def _location(name='Kitchen'):+ return Location.objects.create(+ name=name,+ svg_fragment_filename='kitchen.svg',+ svg_view_box_str='0 0 100 100',+ )++ @staticmethod+ def _selections_json(*pairs):+ return json.dumps([+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: title, DIVID['ATTR_PICKER_SELECTION_URL_KEY']: url}+ for title, url in pairs+ ])++ def _payload(self, owner, selections_json):+ item_type = ItemType.ENTITY if isinstance(owner, Entity) else ItemType.LOCATION+ return {+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(item_type),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: owner.id,+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: selections_json,+ }++ def test_attach_creates_text_attributes_on_entity(self):+ entity = self._entity()+ response = self.client.post(+ self._url(),+ data=self._payload(entity, self._selections_json(+ ('Warranty', 'https://p/doc/1'),+ ('Manual', 'https://p/doc/2'),+ )),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ body = json.loads(response.content)+ self.assertTrue(body.get('refresh'))++ attrs = list(EntityAttribute.objects.filter(entity=entity).order_by('id'))+ self.assertEqual(len(attrs), 2)+ self.assertEqual(attrs[0].name, 'Warranty')+ self.assertEqual(attrs[0].value, 'https://p/doc/1')+ self.assertEqual(attrs[0].value_type, AttributeValueType.TEXT)+ self.assertEqual(attrs[0].attribute_type, AttributeType.CUSTOM)+ self.assertEqual(attrs[1].name, 'Manual')++ def test_attach_creates_text_attribute_on_location(self):+ location = self._location()+ response = self.client.post(+ self._url(),+ data=self._payload(location, self._selections_json(+ ('Floor Plan', 'https://p/doc/floor-plan'),+ )),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ attrs = list(LocationAttribute.objects.filter(location=location))+ self.assertEqual(len(attrs), 1)+ self.assertEqual(attrs[0].name, 'Floor Plan')++ def test_attach_with_empty_selections_creates_nothing(self):+ entity = self._entity()+ response = self.client.post(+ self._url(),+ data=self._payload(entity, json.dumps([])),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertEqual(+ EntityAttribute.objects.filter(entity=entity).count(), 0,+ )++ def test_attach_with_malformed_json_creates_nothing(self):+ # Defensive: malformed JSON yields no attributes rather than+ # a 500. The JS contract submits valid JSON; this guards+ # against a manual replay.+ entity = self._entity()+ response = self.client.post(+ self._url(),+ data=self._payload(entity, 'not-json'),+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ self.assertEqual(+ EntityAttribute.objects.filter(entity=entity).count(), 0,+ )++ def test_attach_skips_records_with_missing_fields(self):+ entity = self._entity()+ payload = self._payload(entity, json.dumps([+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: '', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/1'},+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: 'Good', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/2'},+ {DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: 'No URL', DIVID['ATTR_PICKER_SELECTION_URL_KEY']: ''},+ ]))+ self.client.post(self._url(), data=payload, **self.async_http_headers)+ attrs = list(EntityAttribute.objects.filter(entity=entity).order_by('id'))+ self.assertEqual(len(attrs), 1)+ self.assertEqual(attrs[0].name, 'Good')++ def test_attach_long_title_truncated_to_max_length(self):+ entity = self._entity()+ long_title = 'X' * 100+ payload = self._payload(entity, json.dumps([{+ DIVID['ATTR_PICKER_SELECTION_TITLE_KEY']: long_title,+ DIVID['ATTR_PICKER_SELECTION_URL_KEY']: 'https://p/1',+ }]))+ response = self.client.post(+ self._url(), data=payload, **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 200)+ attr = EntityAttribute.objects.get(entity=entity)+ self.assertEqual(len(attr.name), 64)++ def test_attach_unsupported_item_type_returns_400(self):+ response = self.client.post(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.COLLECTION),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 1,+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: self._selections_json(('A', 'https://p/1')),+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 400)++ def test_attach_unknown_owner_returns_404(self):+ response = self.client.post(+ self._url(),+ data={+ DIVID['ATTR_PICKER_ITEM_TYPE_FIELD']: str(ItemType.ENTITY),+ DIVID['ATTR_PICKER_ITEM_ID_FIELD']: 99999,+ DIVID['ATTR_PICKER_SELECTIONS_JSON_FIELD']: self._selections_json(('A', 'https://p/1')),+ },+ **self.async_http_headers,+ )+ self.assertEqual(response.status_code, 404)diff --git a/src/hi/integrations/tests/test_sync_check.py b/src/hi/integrations/tests/test_sync_check.pyindex 8d7ba3bf..5cfaf719 100644--- a/src/hi/integrations/tests/test_sync_check.py+++ b/src/hi/integrations/tests/test_sync_check.py@@ -664,7 +664,7 @@ class IntegrationConnectorPostSyncHookTests(TestCase):class _TestSynchronizer(IntegrationConnector):SYNCHRONIZATION_LOCK_NAME = 'sync_check_test_lock'- def get_integration_metadata(self):+ def get_metadata(self):return IntegrationMetaData(integration_id=IntegrationConnectorPostSyncHookTests.INTEGRATION_ID,label=IntegrationConnectorPostSyncHookTests.INTEGRATION_LABEL,diff --git a/src/hi/integrations/tests/test_views.py b/src/hi/integrations/tests/test_views.pyindex 6ed0f873..cbdcd3e9 100644--- a/src/hi/integrations/tests/test_views.py+++ b/src/hi/integrations/tests/test_views.py@@ -194,11 +194,16 @@ class _SyncTestSynchronizer:unit tests; the views only need methods the framework actuallycalls on it."""++ # Duck-typed CapabilityGateway surface: the framework reads this+ # when building the attribute edit context.+ capability = IntegrationCapability.CONNECT+def __init__(self, description='Test integration sync description.'):self._description = descriptionself.sync_called = False- def get_description(self, is_initial_connect):+ def get_sync_description(self, is_initial_connect):self.last_is_initial_connect = is_initial_connectreturn self._description@@ -571,11 +576,14 @@ class _PlacementTestSynchronizer:enough to exercise group default, drill-down override, andungrouped per-item paths."""++ capability = IntegrationCapability.CONNECT+def __init__(self, sync_result):self._sync_result = sync_resultself.sync_called = False- def get_description(self, is_initial_connect):+ def get_sync_description(self, is_initial_connect):return Nonedef get_result_title(self, is_initial_connect):diff --git a/src/hi/integrations/urls.py b/src/hi/integrations/urls.pyindex 7f58d3cd..e5c1c1bf 100644--- a/src/hi/integrations/urls.py+++ b/src/hi/integrations/urls.py@@ -10,6 +10,7 @@ from . import viewsurlpatterns = [path( 'connect/', include( 'hi.integrations.connector.urls' )),path( 'import/', include( 'hi.integrations.importer.urls' )),+ path( 'referencer/', include( 'hi.integrations.referencer.urls' )),re_path( r'^placement/(?P<integration_id>[\w\-]+)$',views.IntegrationPlacementView.as_view(),diff --git a/src/hi/integrations/view_mixins.py b/src/hi/integrations/view_mixins.pyindex c11d51b3..e5b2ac64 100644--- a/src/hi/integrations/view_mixins.py+++ b/src/hi/integrations/view_mixins.py@@ -63,17 +63,17 @@ class CapabilityBlockViewMixin:'my_label': 'Import','existing_count': existing_count,'existing_mode_clause': (- 'has data configured as Integration with'+ 'already configured as a Connector with'),'desired_action_clause': (- f'use {integration_data.label} as Import'+ f'use {integration_data.label} as a Data Importer'),'remediation_clause': (f'disable the {integration_data.label} '- f'Integration'+ f'Connector'),'link_url': reverse( 'integrations_connect_home' ),- 'link_label': 'GO TO INTEGRATIONS',+ 'link_label': 'GO TO CONNECTORS',},template_name = 'integrations/modals/capability_blocked.html',)diff --git a/src/hi/integrations/views.py b/src/hi/integrations/views.pyindex 46756912..46dc38dd 100644--- a/src/hi/integrations/views.py+++ b/src/hi/integrations/views.py@@ -57,10 +57,18 @@ class CapabilityConfigureView( HiModalView,def get_template_name( self ) -> str:return self.template_name+ def get_capability_gateway( self, integration_data ):+ """Return the ``CapabilityGateway`` instance for this configure+ view's capability. Subclasses implement by calling the+ appropriate per-capability getter on the gateway. The base+ class deliberately does not enumerate capabilities — each+ subclass already knows its own."""+ raise NotImplementedError('Subclasses must override this method')+def _build_attr_item_context( self, integration_data ):return IntegrationAttributeItemEditContext(integration_data = integration_data,- capability = self.capability,+ capability_gateway = self.get_capability_gateway( integration_data ),update_button_label = self.button_label,suppress_history = True,show_secrets = True,@@ -302,9 +310,12 @@ class IntegrationAttributeHistoryInlineView( View,integration_data = IntegrationManager().get_integration_data(integration_id = attribute.integration.integration_id,)+ # History inline ops target a specific attribute by id; the+ # capability filter inside the edit context is not consulted+ # here, so no capability gateway is needed.attr_item_context = IntegrationAttributeItemEditContext(integration_data = integration_data,- capability = IntegrationCapability.CONNECT,+ capability_gateway = None,)return self.get_history(request = request,@@ -331,9 +342,12 @@ class IntegrationAttributeRestoreInlineView( View,integration_id = attribute.integration.integration_id,)+ # Restore inline ops target a specific attribute by id; the+ # capability filter inside the edit context is not consulted+ # here, so no capability gateway is needed.attr_item_context = IntegrationAttributeItemEditContext(integration_data = integration_data,- capability = IntegrationCapability.CONNECT,+ capability_gateway = None,)return self.post_restore(request = request,diff --git a/src/hi/services/frigate/frigate_connector.py b/src/hi/services/frigate/frigate_connector.pyindex e85052ec..601b020a 100644--- a/src/hi/services/frigate/frigate_connector.py+++ b/src/hi/services/frigate/frigate_connector.py@@ -39,7 +39,7 @@ class FrigateConnector( IntegrationConnector, FrigateMixin ):CAMERA_SNAPSHOT_STREAM_FPS = 1.0- def get_integration_metadata(self):+ def get_metadata(self):return FrigateMetaDatadef get_monitor(self) -> FrigateMonitor:@@ -118,7 +118,7 @@ class FrigateConnector( IntegrationConnector, FrigateMixin ):metadata = { 'event_id': event_id },)- def get_description(self, is_initial_connect : bool) -> Optional[ str ]:+ def get_sync_description(self, is_initial_connect : bool) -> Optional[ str ]:if is_initial_connect:return ('Each Frigate camera becomes a HI camera entity with'diff --git a/src/hi/services/hass/hass_connector.py b/src/hi/services/hass/hass_connector.pyindex 291beb5d..0f5f9acc 100644--- a/src/hi/services/hass/hass_connector.py+++ b/src/hi/services/hass/hass_connector.py@@ -27,7 +27,7 @@ logger = logging.getLogger(__name__)class HassConnector( IntegrationConnector, HassMixin ):- def get_integration_metadata(self):+ def get_metadata(self):return HassMetaDatadef get_monitor(self) -> HassMonitor:@@ -74,7 +74,7 @@ class HassConnector( IntegrationConnector, HassMixin ):return VideoSnapshot( source_url = source_url )- def get_description(self, is_initial_connect: bool) -> Optional[str]:+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:if is_initial_connect:return 'Only items matching your Allowed Item Types setting will be imported.'return 'Only items matching your Allowed Item Types setting are compared.'diff --git a/src/hi/services/homebox/connector/homebox_connector.py b/src/hi/services/homebox/connector/homebox_connector.pyindex f21baac2..0a0efdf8 100644--- a/src/hi/services/homebox/connector/homebox_connector.py+++ b/src/hi/services/homebox/connector/homebox_connector.py@@ -30,7 +30,7 @@ logger = logging.getLogger(__name__)class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):- def get_integration_metadata(self):+ def get_metadata(self):return HbMetaDatadef get_monitor(self) -> HomeBoxMonitor:@@ -45,7 +45,7 @@ class HomeBoxConnector( IntegrationConnector, HomeBoxMixin ):def get_external_view_data(self, entity: Entity) -> Optional[ExternalViewData]:return HomeBoxExternalViewResolver().get_external_view_data(entity)- def get_description(self, is_initial_connect: bool) -> Optional[str]:+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:return ('HomeBox Labels and Locations are kept as metadata on ''each item, not as separate organizational concepts in HI.'diff --git a/src/hi/services/paperless/__init__.py b/src/hi/services/paperless/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/hi/services/paperless/apps.py b/src/hi/services/paperless/apps.pynew file mode 100644index 00000000..c8db2bba--- /dev/null+++ b/src/hi/services/paperless/apps.py@@ -0,0 +1,6 @@+from django.apps import AppConfig+++class PaperlessConfig(AppConfig):+ default_auto_field = 'django.db.models.BigAutoField'+ name = 'hi.services.paperless'diff --git a/src/hi/services/paperless/enums.py b/src/hi/services/paperless/enums.pynew file mode 100644index 00000000..66c94f99--- /dev/null+++ b/src/hi/services/paperless/enums.py@@ -0,0 +1,30 @@+from hi.apps.attribute.enums import AttributeValueType++from hi.integrations.enums import IntegrationAttributeType+++class PlAttributeType( IntegrationAttributeType ):+ """Operator-configurable settings for the paperless integration.++ Two required fields drive the entire ATTRIBUTE_REFERENCE surface:+ the base URL of the paperless server (used by the referencer's+ HTTP client and by the thumbnail proxy) and the API token sent+ as ``Authorization: Token <value>`` on every upstream call.+ """++ API_URL = (+ 'API URL',+ 'e.g., https://paperless.example.com/',+ AttributeValueType.TEXT,+ None,+ True,+ True,+ )+ API_TOKEN = (+ 'API Token',+ 'Paperless token sent as Authorization: Token <value>.',+ AttributeValueType.SECRET,+ None,+ True,+ True,+ )diff --git a/src/hi/services/paperless/integration.py b/src/hi/services/paperless/integration.pynew file mode 100644index 00000000..2c8a96bf--- /dev/null+++ b/src/hi/services/paperless/integration.py@@ -0,0 +1,99 @@+"""Gateway registration entry point for the paperless integration.++ATTRIBUTE_REFERENCE-only: no Connector, no Importer, no monitors.+The gateway returns the referencer and answers configuration /+access validation; the referencer carries the actual search logic.+"""+import logging+from typing import List, Optional+from urllib.parse import urljoin++import requests++from hi.integrations.integration_gateway import IntegrationGateway+from hi.integrations.models import IntegrationAttribute+from hi.integrations.transient_models import (+ ConnectionTestResult,+ IntegrationKey,+ IntegrationMetaData,+ IntegrationValidationResult,+)++from .enums import PlAttributeType+from .pl_metadata import PaperlessMetaData+from .pl_models import PaperlessApi+from .pl_referencer import PaperlessAttributeReferencer+from .pl_validation import validate_attributes+++logger = logging.getLogger(__name__)+++class PaperlessGateway( IntegrationGateway ):++ def get_metadata( self ) -> IntegrationMetaData:+ return PaperlessMetaData++ def get_attribute_referencer( self ) -> PaperlessAttributeReferencer:+ return PaperlessAttributeReferencer()++ def validate_configuration(+ self,+ integration_attributes : List[ IntegrationAttribute ],+ ) -> IntegrationValidationResult:+ return validate_attributes( integration_attributes )++ def validate_access(+ self,+ integration_attributes : List[ IntegrationAttribute ],+ timeout_secs : Optional[float],+ ) -> ConnectionTestResult:+ """Live access probe: a single tiny request against+ ``/api/documents/?page_size=1`` with the configured auth.+ Returns success on 200; the body is irrelevant."""+ schema_result = validate_attributes( integration_attributes )+ if not schema_result.is_valid:+ return ConnectionTestResult.failure( schema_result.error_message )++ attrs_by_key = {+ attr.integration_key: attr for attr in integration_attributes+ }+ api_url = self._attribute_value( attrs_by_key, PlAttributeType.API_URL )+ token = self._attribute_value( attrs_by_key, PlAttributeType.API_TOKEN )+ # Normalize the same way the client does so the probe matches+ # the runtime behavior.+ normalized = api_url.rstrip('/') + '/'+ probe_url = urljoin( normalized, PaperlessApi.DOCUMENTS_PATH )+ try:+ response = requests.get(+ probe_url,+ params = { PaperlessApi.PAGE_SIZE_PARAM: 1 },+ headers = {+ PaperlessApi.AUTH_HEADER: f'{PaperlessApi.AUTH_SCHEME} {token}',+ },+ timeout = timeout_secs if timeout_secs is not None else 5.0,+ )+ except requests.RequestException as e:+ return ConnectionTestResult.failure(+ f'Paperless unreachable: {e}'+ )+ if response.status_code == 200:+ return ConnectionTestResult.success()+ if response.status_code in (401, 403):+ return ConnectionTestResult.failure(+ f'Paperless auth rejected (HTTP {response.status_code}).'+ )+ return ConnectionTestResult.failure(+ f'Paperless responded HTTP {response.status_code}.'+ )++ @staticmethod+ def _attribute_value( attrs_by_key, attr_type : PlAttributeType ) -> str:+ key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str( attr_type ),+ )+ attr = attrs_by_key.get( key )+ if attr is None:+ return ''+ return ( attr.value or '' ).strip()diff --git a/src/hi/services/paperless/pl_client.py b/src/hi/services/paperless/pl_client.pynew file mode 100644index 00000000..37c87b63--- /dev/null+++ b/src/hi/services/paperless/pl_client.py@@ -0,0 +1,150 @@+"""HTTP client for the paperless-ngx ATTRIBUTE_REFERENCE integration.++The client is intentionally small: a single thin wrapper over+``requests.Session`` plus a factory that constructs one from the+stored ``Integration`` attributes. There is no manager singleton —+ATTRIBUTE_REFERENCE has no monitors and no cached state to own, so+each call builds a fresh client from current DB state.++The browser-facing thumbnail URL is built by the *referencer*, not+the client; the client just knows how to fetch upstream once the+caller has a document id.+"""+import logging+from typing import Any, Dict, Optional+from urllib.parse import urljoin++import requests++from hi.integrations.exceptions import IntegrationAttributeError+from hi.integrations.models import Integration+from hi.integrations.transient_models import IntegrationKey++from .enums import PlAttributeType+from .pl_metadata import PaperlessMetaData+from .pl_models import PaperlessApi+++logger = logging.getLogger(__name__)+++class PaperlessClient:+ """Thin paperless-ngx HTTP client. Constructed with the+ configured base URL and API token; both are required and+ non-empty (the factory enforces this).+ """++ DEFAULT_TIMEOUT_SECS = 5.0++ def __init__(+ self,+ api_url : str,+ token : str,+ timeout_secs : Optional[float] = None,+ ):+ # Normalize once at construction so the API_URL is forgiving+ # whether the operator pasted with or without a trailing+ # slash. urljoin then composes paths predictably.+ self.api_url = api_url.rstrip('/') + '/'+ self.token = token+ self._timeout_secs = (+ timeout_secs if timeout_secs is not None+ else self.DEFAULT_TIMEOUT_SECS+ )+ self._session = requests.Session()+ self._session.headers.update({+ PaperlessApi.AUTH_HEADER: f'{PaperlessApi.AUTH_SCHEME} {self.token}',+ })++ def search_documents(+ self,+ query : str,+ page_size : int,+ ) -> Dict[str, Any]:+ """``GET <api_url>/api/documents/?query=<q>&page_size=<n>``;+ returns the parsed JSON envelope (count + results + …)."""+ url = urljoin( self.api_url, PaperlessApi.DOCUMENTS_PATH )+ response = self._session.get(+ url,+ params = {+ PaperlessApi.QUERY_PARAM: query,+ PaperlessApi.PAGE_SIZE_PARAM: page_size,+ },+ timeout = self._timeout_secs,+ )+ response.raise_for_status()+ return response.json()++ def download_thumbnail( self, document_id : int ) -> Dict[str, Any]:+ """Fetch the per-document thumbnail bytes from+ ``/api/documents/<id>/thumb/``. Returns+ ``{'content': bytes, 'mime_type': str}`` — the shape the+ proxy view streams back to the browser."""+ path = PaperlessApi.DOCUMENT_THUMB_PATH.format( id = document_id )+ url = urljoin( self.api_url, path )+ response = self._session.get( url, timeout = self._timeout_secs )+ response.raise_for_status()+ return {+ 'content': response.content,+ 'mime_type': response.headers.get(+ 'Content-Type', 'application/octet-stream',+ ),+ }++ def build_document_details_url( self, document_id : int ) -> str:+ """Per-document web UI URL on the configured paperless server.+ Persisted as the saved attribute's value so an operator+ clicking the link later goes directly to paperless (no HI+ proxy in the path)."""+ path = PaperlessApi.DOCUMENT_DETAILS_PATH.format( id = document_id )+ return urljoin( self.api_url, path )+++def build_client( timeout_secs : Optional[float] = None ) -> PaperlessClient:+ """Construct a PaperlessClient from the configured paperless+ Integration. Looks up the single (per-deployment) paperless+ integration row and reads its API_URL + API_TOKEN attributes.++ Raises:+ Integration.DoesNotExist — paperless integration has never been+ configured.+ IntegrationAttributeError — required attribute is missing,+ empty, or the integration is+ disabled.+ """+ integration = Integration.objects.get(+ integration_id = PaperlessMetaData.integration_id,+ )+ if not integration.is_enabled:+ raise IntegrationAttributeError(+ 'Paperless integration is disabled.'+ )++ attrs_by_key = integration.attributes_by_integration_key+ api_url = _required_attribute_value(+ attrs_by_key, PlAttributeType.API_URL,+ )+ token = _required_attribute_value(+ attrs_by_key, PlAttributeType.API_TOKEN,+ )+ return PaperlessClient(+ api_url = api_url,+ token = token,+ timeout_secs = timeout_secs,+ )+++def _required_attribute_value(+ attrs_by_key : Dict[IntegrationKey, Any],+ attr_type : PlAttributeType,+) -> str:+ key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str( attr_type ),+ )+ attr = attrs_by_key.get( key )+ if attr is None or not (attr.value or '').strip():+ raise IntegrationAttributeError(+ f'Missing paperless attribute: {attr_type.label}'+ )+ return attr.value.strip()diff --git a/src/hi/services/paperless/pl_metadata.py b/src/hi/services/paperless/pl_metadata.pynew file mode 100644index 00000000..fd8f188f--- /dev/null+++ b/src/hi/services/paperless/pl_metadata.py@@ -0,0 +1,25 @@+from hi.integrations.enums import IntegrationCapability+from hi.integrations.transient_models import IntegrationMetaData++from .enums import PlAttributeType+++PaperlessMetaData = IntegrationMetaData(+ # ``paperless`` (not ``paperless-ngx``) for internal naming, in+ # line with how zoneminder / homebox use the short form. The+ # human label keeps the ``-ngx`` suffix.+ integration_id = 'paperless',+ label = 'Paperless-ngx',+ attribute_type = PlAttributeType,+ # Paperless documents become TEXT attributes on existing+ # Entity / Location records via ATTRIBUTE_REFERENCE; the+ # integration never creates HI Entities of its own, so deletion+ # behavior is moot. Internal attributes (those created by HI+ # outside the integration's settings) are not supported here.+ allow_entity_deletion = False,+ allow_internal_attributes = False,+ logo_static_path = 'img/integrations/paperless.png',+ capabilities = frozenset({+ IntegrationCapability.ATTRIBUTE_REFERENCE,+ }),+)diff --git a/src/hi/services/paperless/pl_models.py b/src/hi/services/paperless/pl_models.pynew file mode 100644index 00000000..3c5264f9--- /dev/null+++ b/src/hi/services/paperless/pl_models.py@@ -0,0 +1,45 @@+"""Paperless wire-format constants.++Every string that crosses the wire to a paperless-ngx server lives+here: API path templates, JSON field names in responses, and the+authorization scheme. The client and referencer pull from this+single class so a wire-side rename is a one-file edit.+"""+++class PaperlessApi:+ """Wire-format strings shared between the client and the+ referencer. Paths are appended to the configured ``API_URL``+ base; ``{id}`` is the per-document substitution token."""++ # ---- URL paths (relative to the configured API_URL) ----++ DOCUMENTS_PATH = 'api/documents/'+ DOCUMENT_THUMB_PATH = 'api/documents/{id}/thumb/'+ # Per-document web UI route. Used unchanged as the persisted+ # attribute value; operators clicking the saved link land on+ # paperless's own page (authenticated by their paperless session,+ # not by HI).+ DOCUMENT_DETAILS_PATH = 'documents/{id}/details/'++ # ---- Query parameters ----++ QUERY_PARAM = 'query'+ PAGE_SIZE_PARAM = 'page_size'++ # ---- Authorization ----++ AUTH_HEADER = 'Authorization'+ AUTH_SCHEME = 'Token' # ``Authorization: Token <value>``++ # ---- Documents-list response JSON keys ----++ RESPONSE_COUNT = 'count'+ RESPONSE_RESULTS = 'results'++ # ---- Per-document JSON keys ----++ DOC_ID = 'id'+ DOC_TITLE = 'title'+ DOC_CONTENT = 'content'+ DOC_MIME_TYPE = 'mime_type'diff --git a/src/hi/services/paperless/pl_referencer.py b/src/hi/services/paperless/pl_referencer.pynew file mode 100644index 00000000..e34630d3--- /dev/null+++ b/src/hi/services/paperless/pl_referencer.py@@ -0,0 +1,172 @@+"""ATTRIBUTE_REFERENCE implementation for paperless-ngx.++Translates each paperless documents-search hit into a single+``AttributeReferenceResult``:++ - ``title`` → document title (verbatim)+ - ``source_url`` → upstream per-document URL on the configured+ paperless server. Persisted as the saved+ attribute's value; operators clicking the+ saved link go directly to paperless and+ authenticate via their own paperless session.+ - ``thumbnail_url`` → HI's thumbnail-proxy URL. The picker renders+ this as <img src=…>; the browser's request+ carries the HI session (not the paperless+ API token), and HI fetches the upstream+ thumbnail server-side.+ - ``mime_type`` → upstream document MIME (drives the picker's+ fallback-icon path when no thumbnail).+ - ``snippet`` → ~160-char window around the query match in+ the document's content. Paperless's search+ endpoint returns full ``content`` per hit;+ we extract a window client-side rather than+ persist or display the whole document text.+"""+import logging+from typing import List, Optional++from django.urls import reverse+from requests import HTTPError++from hi.integrations.exceptions import IntegrationAttributeError+from hi.integrations.referencer.integration_referencer import (+ IntegrationAttributeReferencer,+)+from hi.integrations.referencer.transient_models import (+ AttributeReferenceResult,+)+from hi.integrations.transient_models import (+ IntegrationMetaData,+ IntegrationValidationResult,+)++from .pl_client import PaperlessClient, build_client+from .pl_metadata import PaperlessMetaData+from .pl_models import PaperlessApi+from .pl_validation import validate_attributes+++logger = logging.getLogger(__name__)+++class PaperlessAttributeReferencer( IntegrationAttributeReferencer ):++ # Window cap matches the picker's snippet rendering — long+ # enough to carry useful context, short enough to keep cards+ # compact and the query visible.+ SNIPPET_WINDOW = 160+ # Characters before the matched query to include as leading+ # context. The trailing context fills the remainder up to+ # ``SNIPPET_WINDOW``.+ SNIPPET_LEAD = 40++ def get_metadata( self ) -> IntegrationMetaData:+ return PaperlessMetaData++ def validate_configuration(+ self,+ integration_attributes,+ ) -> IntegrationValidationResult:+ return validate_attributes( integration_attributes )++ def search_references(+ self,+ query : str,+ limit : int = 20,+ ) -> List[ AttributeReferenceResult ]:+ if not query or not query.strip():+ return []+ try:+ client = build_client()+ except IntegrationAttributeError as e:+ logger.warning( f'Paperless search aborted: {e}' )+ return []+ except Exception as e:+ logger.exception( f'Paperless client build failed: {e}' )+ return []++ try:+ envelope = client.search_documents(+ query = query.strip(), page_size = limit,+ )+ except HTTPError as e:+ status = getattr( e.response, 'status_code', None )+ logger.warning(+ f'Paperless search HTTP {status} for query '+ f'{query!r}: {e}'+ )+ return []+ except Exception as e:+ logger.warning(+ f'Paperless search failed for query {query!r}: {e}'+ )+ return []++ documents = envelope.get( PaperlessApi.RESPONSE_RESULTS, [] ) or []+ return [+ self._translate( client = client, document = doc, query = query )+ for doc in documents+ ]++ def _translate(+ self,+ client : PaperlessClient,+ document : dict,+ query : str,+ ) -> AttributeReferenceResult:+ document_id = document.get( PaperlessApi.DOC_ID )+ title = document.get( PaperlessApi.DOC_TITLE ) or ''+ content = document.get( PaperlessApi.DOC_CONTENT ) or ''+ mime_type = document.get( PaperlessApi.DOC_MIME_TYPE )+ return AttributeReferenceResult(+ title = title,+ source_url = client.build_document_details_url( document_id ),+ thumbnail_url = self._proxy_thumbnail_url( document_id ),+ mime_type = mime_type,+ snippet = self._extract_snippet( content = content, query = query ),+ )++ @staticmethod+ def _proxy_thumbnail_url( document_id : int ) -> str:+ # HI-internal URL that streams the upstream thumbnail through+ # the configured token. The picker renders <img src=…> so the+ # browser fetches this under HI's session.+ return reverse(+ 'paperless_thumbnail',+ kwargs = { 'document_id': document_id },+ )++ @classmethod+ def _extract_snippet(+ cls, content : str, query : str,+ ) -> Optional[str]:+ """Return a short window around the query match inside the+ document content. Falls back to the document's leading+ characters when the query isn't found verbatim (e.g.,+ paperless matched on a stemmed form). Returns None when+ there is no content at all so the picker leaves the snippet+ row out entirely."""+ if not content:+ return None+ if not query:+ return cls._truncate( content, cls.SNIPPET_WINDOW )++ lowered_content = content.lower()+ lowered_query = query.strip().lower()+ idx = lowered_content.find( lowered_query )+ if idx < 0:+ return cls._truncate( content, cls.SNIPPET_WINDOW )++ start = max( 0, idx - cls.SNIPPET_LEAD )+ end = min( len(content), start + cls.SNIPPET_WINDOW )+ snippet = content[ start : end ]+ prefix = '…' if start > 0 else ''+ suffix = '…' if end < len(content) else ''+ return f'{prefix}{snippet}{suffix}'++ @staticmethod+ def _truncate( content : str, max_chars : int ) -> str:+ stripped = content.strip()+ if len(stripped) <= max_chars:+ return stripped+ return stripped[:max_chars].rstrip() + '…'diff --git a/src/hi/services/paperless/pl_validation.py b/src/hi/services/paperless/pl_validation.pynew file mode 100644index 00000000..4c210dfe--- /dev/null+++ b/src/hi/services/paperless/pl_validation.py@@ -0,0 +1,77 @@+"""Configuration validation for the paperless integration.++Shared between the referencer (``validate_configuration``) and the+gateway (``validate_configuration`` + ``validate_access``). Pure+schema-level checks live in ``validate_attributes``; the+network-probing access check is in the gateway proper.+"""+from typing import Dict, List+from urllib.parse import urlparse++from hi.apps.system.enums import HealthStatusType+from hi.integrations.models import IntegrationAttribute+from hi.integrations.transient_models import (+ IntegrationKey,+ IntegrationValidationResult,+)++from .enums import PlAttributeType+from .pl_metadata import PaperlessMetaData+++_VALID_SCHEMES = frozenset({ 'http', 'https' })+++def validate_attributes(+ integration_attributes : List[ IntegrationAttribute ],+) -> IntegrationValidationResult:+ """Schema-only validation: required attributes present and+ non-empty; API_URL has http(s) scheme and a netloc. Does NOT+ perform network operations."""+ attrs_by_key = _attributes_by_key( integration_attributes )++ api_url = _value( attrs_by_key, PlAttributeType.API_URL )+ if not api_url:+ return IntegrationValidationResult.error(+ status = HealthStatusType.WARNING,+ error_message = f'Missing required attribute: {PlAttributeType.API_URL.label}',+ )++ parsed = urlparse( api_url )+ if parsed.scheme not in _VALID_SCHEMES or not parsed.netloc:+ return IntegrationValidationResult.error(+ status = HealthStatusType.WARNING,+ error_message = (+ f'{PlAttributeType.API_URL.label} must be an http(s) URL '+ f'with a hostname; got {api_url!r}.'+ ),+ )++ token = _value( attrs_by_key, PlAttributeType.API_TOKEN )+ if not token:+ return IntegrationValidationResult.error(+ status = HealthStatusType.WARNING,+ error_message = f'Missing required attribute: {PlAttributeType.API_TOKEN.label}',+ )++ return IntegrationValidationResult.success()+++def _attributes_by_key(+ integration_attributes : List[ IntegrationAttribute ],+) -> Dict[ IntegrationKey, IntegrationAttribute ]:+ return { attr.integration_key: attr for attr in integration_attributes }+++def _value(+ attrs_by_key : Dict[ IntegrationKey, IntegrationAttribute ],+ attr_type : PlAttributeType,+) -> str:+ key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str( attr_type ),+ )+ attr = attrs_by_key.get( key )+ if attr is None:+ return ''+ return ( attr.value or '' ).strip()diff --git a/src/hi/services/paperless/tests/__init__.py b/src/hi/services/paperless/tests/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/hi/services/paperless/tests/test_pl_client.py b/src/hi/services/paperless/tests/test_pl_client.pynew file mode 100644index 00000000..86162e25--- /dev/null+++ b/src/hi/services/paperless/tests/test_pl_client.py@@ -0,0 +1,152 @@+"""Tests for the paperless HTTP client and its factory.++The client is a thin requests wrapper; tests cover URL composition,+auth header, the documents-search + thumbnail-download calls, and+the trailing-slash forgiving normalization. The factory tests cover+the DB-driven config lookup, including the disabled-integration and+missing-attribute paths that should refuse to hand back a client.+"""+import logging+from unittest.mock import Mock, patch++from django.test import TestCase++from hi.apps.attribute.enums import AttributeValueType+from hi.integrations.exceptions import IntegrationAttributeError+from hi.integrations.models import Integration, IntegrationAttribute+from hi.integrations.transient_models import IntegrationKey++from hi.services.paperless.enums import PlAttributeType+from hi.services.paperless.pl_client import PaperlessClient, build_client+from hi.services.paperless.pl_metadata import PaperlessMetaData+++logging.disable(logging.CRITICAL)+++def _make_attr(integration, attr_type, value):+ attr = IntegrationAttribute(+ integration = integration,+ name = attr_type.label,+ value = value,+ value_type_str = str(AttributeValueType.TEXT),+ attribute_type_str = 'PREDEFINED',+ )+ attr.integration_key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str(attr_type),+ )+ attr.save()+ return attr+++class TestPaperlessClient(TestCase):++ def test_trailing_slash_normalized(self):+ # The factory forgives operators who paste with or without a+ # trailing slash; both should yield the same upstream URLs.+ c1 = PaperlessClient(api_url = 'https://p.example.com', token = 't')+ c2 = PaperlessClient(api_url = 'https://p.example.com/', token = 't')+ self.assertEqual(c1.api_url, 'https://p.example.com/')+ self.assertEqual(c2.api_url, 'https://p.example.com/')++ def test_auth_header_set_on_session(self):+ client = PaperlessClient(api_url = 'https://p.example.com', token = 'abc')+ self.assertEqual(+ client._session.headers['Authorization'],+ 'Token abc',+ )++ def test_search_documents_dispatches_and_returns_json(self):+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')+ envelope = {'count': 2, 'results': [{'id': 1}, {'id': 2}]}+ response = Mock()+ response.json.return_value = envelope+ response.raise_for_status = Mock()+ with patch.object(client._session, 'get', return_value = response) as mock_get:+ result = client.search_documents(query = 'dishwasher', page_size = 50)++ self.assertEqual(result, envelope)+ args, kwargs = mock_get.call_args+ # URL composes against the normalized base.+ self.assertEqual(args[0], 'https://p.example.com/api/documents/')+ self.assertEqual(kwargs['params']['query'], 'dishwasher')+ self.assertEqual(kwargs['params']['page_size'], 50)++ def test_download_thumbnail_returns_bytes_and_mime(self):+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')+ response = Mock()+ response.content = b'PNG-BYTES'+ response.headers = {'Content-Type': 'image/png'}+ response.raise_for_status = Mock()+ with patch.object(client._session, 'get', return_value = response) as mock_get:+ result = client.download_thumbnail(document_id = 42)++ self.assertEqual(result, {'content': b'PNG-BYTES', 'mime_type': 'image/png'})+ args, _ = mock_get.call_args+ self.assertEqual(args[0], 'https://p.example.com/api/documents/42/thumb/')++ def test_download_thumbnail_default_mime_when_missing(self):+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')+ response = Mock()+ response.content = b'raw'+ response.headers = {}+ response.raise_for_status = Mock()+ with patch.object(client._session, 'get', return_value = response):+ result = client.download_thumbnail(document_id = 1)+ self.assertEqual(result['mime_type'], 'application/octet-stream')++ def test_build_document_details_url(self):+ client = PaperlessClient(api_url = 'https://p.example.com/', token = 't')+ self.assertEqual(+ client.build_document_details_url(document_id = 7),+ 'https://p.example.com/documents/7/details/',+ )+++class TestBuildClient(TestCase):++ def setUp(self):+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = True,+ )++ def test_returns_configured_client(self):+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com')+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'abc')+ client = build_client()+ self.assertIsInstance(client, PaperlessClient)+ # Trailing slash normalized.+ self.assertEqual(client.api_url, 'https://paperless.example.com/')+ self.assertEqual(client.token, 'abc')++ def test_no_integration_row_raises(self):+ # Wipe the row created in setUp.+ Integration.objects.all().delete()+ with self.assertRaises(Integration.DoesNotExist):+ build_client()++ def test_disabled_integration_raises(self):+ self.integration.is_enabled = False+ self.integration.save()+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com')+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'abc')+ with self.assertRaises(IntegrationAttributeError):+ build_client()++ def test_missing_attribute_raises(self):+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com')+ # API_TOKEN deliberately omitted.+ with self.assertRaises(IntegrationAttributeError):+ build_client()++ def test_empty_attribute_value_raises(self):+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com')+ _make_attr(self.integration, PlAttributeType.API_TOKEN, ' ')+ with self.assertRaises(IntegrationAttributeError):+ build_client()diff --git a/src/hi/services/paperless/tests/test_pl_gateway.py b/src/hi/services/paperless/tests/test_pl_gateway.pynew file mode 100644index 00000000..8c9a7e11--- /dev/null+++ b/src/hi/services/paperless/tests/test_pl_gateway.py@@ -0,0 +1,123 @@+"""Gateway tests: capability registration + validate_access probe.++Schema validation is exercised in detail in test_pl_validation; this+file covers the gateway's wiring to the referencer and the network+probe it runs for the "Test Connection" path.+"""+import logging+from unittest.mock import Mock, patch++from django.test import TestCase+from requests import RequestException++from hi.apps.attribute.enums import AttributeValueType+from hi.integrations.enums import IntegrationCapability+from hi.integrations.models import Integration, IntegrationAttribute+from hi.integrations.transient_models import IntegrationKey++from hi.services.paperless.enums import PlAttributeType+from hi.services.paperless.integration import PaperlessGateway+from hi.services.paperless.pl_metadata import PaperlessMetaData+from hi.services.paperless.pl_referencer import PaperlessAttributeReferencer+++logging.disable(logging.CRITICAL)+++def _make_attr(integration, attr_type, value):+ attr = IntegrationAttribute(+ integration = integration,+ name = attr_type.label,+ value = value,+ value_type_str = str(AttributeValueType.TEXT),+ attribute_type_str = 'PREDEFINED',+ )+ attr.integration_key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str(attr_type),+ )+ return attr+++class TestPaperlessGatewayWiring(TestCase):++ def test_metadata_declares_attribute_reference(self):+ meta = PaperlessGateway().get_metadata()+ self.assertEqual(meta.integration_id, 'paperless')+ self.assertEqual(meta.label, 'Paperless-ngx')+ self.assertIn(IntegrationCapability.ATTRIBUTE_REFERENCE,+ meta.capabilities)++ def test_returns_referencer(self):+ referencer = PaperlessGateway().get_attribute_referencer()+ self.assertIsInstance(referencer, PaperlessAttributeReferencer)+++class TestValidateAccess(TestCase):++ def setUp(self):+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = True,+ )+ self.attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com'),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),+ ]++ @patch('hi.services.paperless.integration.requests.get')+ def test_200_response_returns_success(self, mock_get):+ mock_get.return_value = Mock(status_code = 200)+ result = PaperlessGateway().validate_access(+ integration_attributes = self.attrs,+ timeout_secs = 1.0,+ )+ self.assertTrue(result.is_success)+ # Probe issues a single tiny request — page_size=1 keeps the+ # upstream cost minimal.+ _, kwargs = mock_get.call_args+ self.assertEqual(kwargs['params']['page_size'], 1)+ self.assertEqual(kwargs['headers']['Authorization'], 'Token token-abc')++ @patch('hi.services.paperless.integration.requests.get')+ def test_401_returns_auth_failure(self, mock_get):+ mock_get.return_value = Mock(status_code = 401)+ result = PaperlessGateway().validate_access(+ integration_attributes = self.attrs, timeout_secs = 1.0,+ )+ self.assertFalse(result.is_success)+ self.assertIn('auth', result.message.lower())++ @patch('hi.services.paperless.integration.requests.get')+ def test_5xx_returns_failure(self, mock_get):+ mock_get.return_value = Mock(status_code = 503)+ result = PaperlessGateway().validate_access(+ integration_attributes = self.attrs, timeout_secs = 1.0,+ )+ self.assertFalse(result.is_success)+ self.assertIn('503', result.message)++ @patch('hi.services.paperless.integration.requests.get',+ side_effect = RequestException('refused'))+ def test_unreachable_returns_failure(self, _mock_get):+ result = PaperlessGateway().validate_access(+ integration_attributes = self.attrs, timeout_secs = 1.0,+ )+ self.assertFalse(result.is_success)+ self.assertIn('unreachable', result.message.lower())++ def test_schema_invalid_short_circuits(self):+ # When attributes don't even pass schema validation we must+ # not attempt the network call. patch.object on requests.get+ # asserts no call.+ bad_attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL, ''),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'tok'),+ ]+ with patch('hi.services.paperless.integration.requests.get') as mock_get:+ result = PaperlessGateway().validate_access(+ integration_attributes = bad_attrs, timeout_secs = 1.0,+ )+ self.assertFalse(result.is_success)+ mock_get.assert_not_called()diff --git a/src/hi/services/paperless/tests/test_pl_proxy_views.py b/src/hi/services/paperless/tests/test_pl_proxy_views.pynew file mode 100644index 00000000..377c2c9b--- /dev/null+++ b/src/hi/services/paperless/tests/test_pl_proxy_views.py@@ -0,0 +1,81 @@+"""Tests for the paperless thumbnail proxy view.++Mirrors the HomeBox attachment-proxy test shape: unconfigured+integration → 404; upstream 404 → 404; other upstream failures →+502; success → 200 with passthrough bytes + content-type.+"""+import logging+from unittest.mock import Mock, patch++from django.test import TestCase+from django.urls import reverse+from requests import HTTPError, RequestException++from hi.integrations.exceptions import IntegrationAttributeError+++logging.disable(logging.CRITICAL)+++class TestThumbnailProxyView(TestCase):++ def _url(self, document_id: int = 1) -> str:+ return reverse(+ 'paperless_thumbnail',+ kwargs = {'document_id': document_id},+ )++ @patch('hi.services.paperless.views.build_client',+ side_effect = IntegrationAttributeError('not configured'))+ def test_unconfigured_returns_404(self, _mock_build):+ response = self.client.get(self._url())+ self.assertEqual(response.status_code, 404)++ @patch('hi.services.paperless.views.build_client')+ def test_successful_download_returns_bytes_and_mime(self, mock_build):+ client = Mock()+ client.download_thumbnail.return_value = {+ 'content': b'PNG-BYTES',+ 'mime_type': 'image/png',+ }+ mock_build.return_value = client++ response = self.client.get(self._url(document_id = 42))++ self.assertEqual(response.status_code, 200)+ self.assertEqual(response.content, b'PNG-BYTES')+ self.assertEqual(response['Content-Type'], 'image/png')+ client.download_thumbnail.assert_called_once_with(document_id = 42)++ @patch('hi.services.paperless.views.build_client')+ def test_upstream_404_returns_404(self, mock_build):+ client = Mock()+ response = Mock()+ response.status_code = 404+ client.download_thumbnail.side_effect = HTTPError('404', response = response)+ mock_build.return_value = client++ result = self.client.get(self._url())+ self.assertEqual(result.status_code, 404)++ @patch('hi.services.paperless.views.build_client')+ def test_upstream_401_returns_502(self, mock_build):+ # Auth-level failures still get the bad-gateway treatment;+ # the browser sees "upstream trouble", not "doc missing".+ client = Mock()+ response = Mock()+ response.status_code = 401+ client.download_thumbnail.side_effect = HTTPError('401', response = response)+ mock_build.return_value = client++ result = self.client.get(self._url())+ self.assertEqual(result.status_code, 502)++ @patch('hi.services.paperless.views.build_client')+ def test_connection_error_returns_502(self, mock_build):+ client = Mock()+ client.download_thumbnail.side_effect = RequestException('boom')+ mock_build.return_value = client++ result = self.client.get(self._url())+ self.assertEqual(result.status_code, 502)diff --git a/src/hi/services/paperless/tests/test_pl_referencer.py b/src/hi/services/paperless/tests/test_pl_referencer.pynew file mode 100644index 00000000..b0a7e679--- /dev/null+++ b/src/hi/services/paperless/tests/test_pl_referencer.py@@ -0,0 +1,247 @@+"""Tests for the ATTRIBUTE_REFERENCE referencer.++Covers the two surfaces that matter for picker UX: snippet+extraction (window around the matched query, with paperless-style+fallbacks when no match) and the end-to-end translation of a+paperless documents-search response into AttributeReferenceResult+rows the framework can hand to the picker.+"""+import logging+from unittest.mock import Mock, patch++from django.test import TestCase+from requests import HTTPError++from hi.apps.attribute.enums import AttributeValueType+from hi.integrations.exceptions import IntegrationAttributeError+from hi.integrations.models import Integration, IntegrationAttribute+from hi.integrations.transient_models import IntegrationKey++from hi.services.paperless.enums import PlAttributeType+from hi.services.paperless.pl_metadata import PaperlessMetaData+from hi.services.paperless.pl_referencer import PaperlessAttributeReferencer+++logging.disable(logging.CRITICAL)+++def _make_attr(integration, attr_type, value):+ attr = IntegrationAttribute(+ integration = integration,+ name = attr_type.label,+ value = value,+ value_type_str = str(AttributeValueType.TEXT),+ attribute_type_str = 'PREDEFINED',+ )+ attr.integration_key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str(attr_type),+ )+ attr.save()+ return attr+++class TestSnippetExtraction(TestCase):++ def test_none_for_empty_content(self):+ # Empty content => omit the snippet row entirely in the+ # picker rather than render an empty placeholder.+ self.assertIsNone(+ PaperlessAttributeReferencer._extract_snippet(+ content = '', query = 'q',+ )+ )++ def test_short_content_returned_verbatim(self):+ self.assertEqual(+ PaperlessAttributeReferencer._extract_snippet(+ content = 'Short doc text.', query = 'missing',+ ),+ 'Short doc text.',+ )++ def test_long_content_without_match_truncates(self):+ result = PaperlessAttributeReferencer._extract_snippet(+ content = 'A' * 500, query = 'missing',+ )+ self.assertLessEqual(len(result), 161) # 160 + the ellipsis+ self.assertTrue(result.endswith('…'))++ def test_match_in_middle_emits_leading_and_trailing_ellipses(self):+ content = 'x' * 200 + ' DISHWASHER ' + 'y' * 200+ result = PaperlessAttributeReferencer._extract_snippet(+ content = content, query = 'dishwasher',+ )+ self.assertIn('DISHWASHER', result)+ self.assertTrue(result.startswith('…'))+ self.assertTrue(result.endswith('…'))++ def test_match_at_start_no_leading_ellipsis(self):+ result = PaperlessAttributeReferencer._extract_snippet(+ content = 'Warranty info follows.', query = 'warranty',+ )+ self.assertFalse(result.startswith('…'))++ def test_case_insensitive_match(self):+ result = PaperlessAttributeReferencer._extract_snippet(+ content = 'The DISHWASHER manual.', query = 'dishwasher',+ )+ self.assertIn('DISHWASHER', result)+++class TestSearchReferences(TestCase):+ """End-to-end search via a mocked PaperlessClient."""++ def setUp(self):+ self.referencer = PaperlessAttributeReferencer()++ def _envelope(self, *docs):+ return {'count': len(docs), 'results': list(docs)}++ def _doc(self, doc_id, **kwargs):+ d = {+ 'id': doc_id,+ 'title': f'Doc {doc_id}',+ 'content': 'Some content text.',+ 'mime_type': 'application/pdf',+ }+ d.update(kwargs)+ return d++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_empty_query_returns_empty_without_dispatch(self, mock_build):+ # Short-circuit so the picker can render a blank initial+ # modal without provoking an upstream call.+ result = self.referencer.search_references(query = '', limit = 20)+ self.assertEqual(result, [])+ mock_build.assert_not_called()++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_whitespace_query_returns_empty(self, mock_build):+ result = self.referencer.search_references(query = ' ', limit = 20)+ self.assertEqual(result, [])+ mock_build.assert_not_called()++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_translates_paperless_documents_to_results(self, mock_build):+ client = Mock()+ client.search_documents.return_value = self._envelope(+ self._doc(1, title = 'Warranty',+ content = 'Warranty terms for the unit.'),+ self._doc(2, title = 'Manual',+ content = 'Installation manual.', mime_type = 'text/plain'),+ )+ client.build_document_details_url.side_effect = (+ lambda id: f'https://p.example.com/documents/{id}/details/'+ )+ mock_build.return_value = client++ results = self.referencer.search_references(+ query = 'warranty', limit = 20,+ )++ self.assertEqual(len(results), 2)+ self.assertEqual(results[0].title, 'Warranty')+ self.assertEqual(+ results[0].source_url,+ 'https://p.example.com/documents/1/details/',+ )+ # Thumbnail is the HI proxy URL, NOT the upstream URL — the+ # browser fetches via HI's session and HI fetches upstream+ # with the configured token.+ self.assertIn('/integration/services/paperless/documents/1/thumb/',+ results[0].thumbnail_url)+ self.assertEqual(results[0].mime_type, 'application/pdf')+ self.assertIn('Warranty', results[0].snippet)++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_limit_is_passed_through_as_page_size(self, mock_build):+ client = Mock()+ client.search_documents.return_value = self._envelope()+ client.build_document_details_url.side_effect = (+ lambda id: f'https://p.example.com/documents/{id}/details/'+ )+ mock_build.return_value = client++ self.referencer.search_references(query = 'q', limit = 50)+ client.search_documents.assert_called_once_with(+ query = 'q', page_size = 50,+ )++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_missing_results_key_yields_empty(self, mock_build):+ # Defensive: don't blow up if upstream's envelope omits the+ # results key (or sends null).+ client = Mock()+ client.search_documents.return_value = {'count': 0}+ client.build_document_details_url.side_effect = (+ lambda id: f'https://p.example.com/documents/{id}/details/'+ )+ mock_build.return_value = client+ self.assertEqual(+ self.referencer.search_references(query = 'q', limit = 20),+ [],+ )++ @patch('hi.services.paperless.pl_referencer.build_client',+ side_effect = IntegrationAttributeError('not configured'))+ def test_unconfigured_integration_returns_empty(self, _mock_build):+ # Operator opens the picker before configuring the+ # integration — referencer must fail soft so the modal can+ # render an empty result list rather than 500.+ self.assertEqual(+ self.referencer.search_references(query = 'q', limit = 20),+ [],+ )++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_upstream_http_error_returns_empty(self, mock_build):+ client = Mock()+ response = Mock()+ response.status_code = 401+ error = HTTPError('401', response = response)+ client.search_documents.side_effect = error+ mock_build.return_value = client+ self.assertEqual(+ self.referencer.search_references(query = 'q', limit = 20),+ [],+ )++ @patch('hi.services.paperless.pl_referencer.build_client')+ def test_unexpected_exception_returns_empty(self, mock_build):+ client = Mock()+ client.search_documents.side_effect = RuntimeError('boom')+ mock_build.return_value = client+ self.assertEqual(+ self.referencer.search_references(query = 'q', limit = 20),+ [],+ )+++class TestValidateConfiguration(TestCase):+ """``validate_configuration`` is the schema check delegated to+ ``pl_validation.validate_attributes`` (covered there in detail).+ Smoke-test that the referencer forwards correctly."""++ def setUp(self):+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = True,+ )++ def test_success_when_attributes_valid(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com/'),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),+ ]+ result = PaperlessAttributeReferencer().validate_configuration(attrs)+ self.assertTrue(result.is_valid)++ def test_error_when_token_missing(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com/'),+ ]+ result = PaperlessAttributeReferencer().validate_configuration(attrs)+ self.assertFalse(result.is_valid)diff --git a/src/hi/services/paperless/tests/test_pl_validation.py b/src/hi/services/paperless/tests/test_pl_validation.pynew file mode 100644index 00000000..734ec88d--- /dev/null+++ b/src/hi/services/paperless/tests/test_pl_validation.py@@ -0,0 +1,104 @@+"""Schema-only validation for paperless integration attributes.++Validation is shared between the gateway's+``validate_configuration`` and the referencer's, so tests target the+helper directly. Network probes belong to ``validate_access`` —+covered separately.+"""+import logging++from django.test import TestCase++from hi.apps.attribute.enums import AttributeValueType+from hi.apps.system.enums import HealthStatusType+from hi.integrations.models import Integration, IntegrationAttribute+from hi.integrations.transient_models import IntegrationKey++from hi.services.paperless.enums import PlAttributeType+from hi.services.paperless.pl_metadata import PaperlessMetaData+from hi.services.paperless.pl_validation import validate_attributes+++logging.disable(logging.CRITICAL)+++def _make_attr(integration, attr_type, value):+ attr = IntegrationAttribute(+ integration = integration,+ name = attr_type.label,+ value = value,+ value_type_str = str(AttributeValueType.TEXT),+ attribute_type_str = 'PREDEFINED',+ )+ attr.integration_key = IntegrationKey(+ integration_id = PaperlessMetaData.integration_id,+ integration_name = str(attr_type),+ )+ return attr+++class TestValidateAttributes(TestCase):++ def setUp(self):+ self.integration = Integration.objects.create(+ integration_id = PaperlessMetaData.integration_id,+ is_enabled = True,+ )++ def test_all_present_and_valid_returns_success(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com/'),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),+ ]+ result = validate_attributes(attrs)+ self.assertTrue(result.is_valid)+ self.assertEqual(result.status, HealthStatusType.HEALTHY)++ def test_missing_api_url_returns_error(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),+ ]+ result = validate_attributes(attrs)+ self.assertFalse(result.is_valid)+ self.assertIn('API URL', result.error_message)++ def test_missing_token_returns_error(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'https://paperless.example.com/'),+ ]+ result = validate_attributes(attrs)+ self.assertFalse(result.is_valid)+ self.assertIn('API Token', result.error_message)++ def test_empty_value_treated_as_missing(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL, ' '),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token-abc'),+ ]+ result = validate_attributes(attrs)+ self.assertFalse(result.is_valid)+ self.assertIn('API URL', result.error_message)++ def test_invalid_scheme_returns_error(self):+ # File / FTP / scheme-less URLs are rejected; the client uses+ # requests' HTTP-only session, so allowing them would surface+ # as a cryptic runtime failure rather than a config-time one.+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL,+ 'ftp://paperless.example.com/'),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),+ ]+ result = validate_attributes(attrs)+ self.assertFalse(result.is_valid)+ self.assertIn('http(s)', result.error_message)++ def test_missing_netloc_returns_error(self):+ attrs = [+ _make_attr(self.integration, PlAttributeType.API_URL, 'https://'),+ _make_attr(self.integration, PlAttributeType.API_TOKEN, 'token'),+ ]+ result = validate_attributes(attrs)+ self.assertFalse(result.is_valid)+ self.assertIn('hostname', result.error_message)diff --git a/src/hi/services/paperless/urls.py b/src/hi/services/paperless/urls.pynew file mode 100644index 00000000..2a02cfda--- /dev/null+++ b/src/hi/services/paperless/urls.py@@ -0,0 +1,20 @@+"""Per-integration URL extension point.++Mounts under ``services/paperless/`` via the framework's+auto-discovery (see hi/integrations/urls.py). One route: a thumbnail+proxy used by the ATTRIBUTE_REFERENCE picker so browser-rendered+<img> tags can fetch paperless thumbnails through HI's session+instead of requiring the upstream paperless API token.+"""+from django.urls import path++from .views import ThumbnailProxyView+++urlpatterns = [+ path(+ 'documents/<int:document_id>/thumb/',+ ThumbnailProxyView.as_view(),+ name = 'paperless_thumbnail',+ ),+]diff --git a/src/hi/services/paperless/views.py b/src/hi/services/paperless/views.pynew file mode 100644index 00000000..881790a4--- /dev/null+++ b/src/hi/services/paperless/views.py@@ -0,0 +1,62 @@+"""Browser-facing paperless views.++Only a thumbnail proxy lives here. Document source links go directly+to paperless's web UI (the operator authenticates with paperless via+their own session), but thumbnails are embedded inside the HI picker+modal so the browser cannot supply the upstream API token. The proxy+fetches server-side with the configured token and streams bytes back+under HI's session — same approach HomeBox uses for its attachments.+"""+import logging++from django.http import Http404, HttpResponse+from django.views import View+from requests import HTTPError++from hi.integrations.exceptions import IntegrationAttributeError+from hi.integrations.models import Integration++from .pl_client import build_client++logger = logging.getLogger(__name__)+++class ThumbnailProxyView( View ):++ def get( self, request, document_id : int ):+ try:+ client = build_client()+ except (Integration.DoesNotExist, IntegrationAttributeError):+ raise Http404('Paperless integration not configured.')++ try:+ downloaded = client.download_thumbnail(+ document_id = document_id,+ )+ except HTTPError as e:+ status = getattr( e.response, 'status_code', None )+ if status == 404:+ raise Http404('Thumbnail not found.')+ logger.warning(+ f'Paperless thumb proxy HTTP {status} '+ f'for document {document_id}: {e}'+ )+ return HttpResponse(+ status = 502, content = 'Paperless upstream error.',+ )+ except Exception as e:+ # Upstream connectivity / auth / parse failure. Surface+ # as 502 so the browser distinguishes upstream trouble+ # from a missing document.+ logger.warning(+ f'Paperless thumb proxy failed '+ f'for document {document_id}: {e}'+ )+ return HttpResponse(+ status = 502, content = 'Paperless upstream error.',+ )++ return HttpResponse(+ content = downloaded['content'],+ content_type = downloaded['mime_type'],+ )diff --git a/src/hi/services/zoneminder/zm_connector.py b/src/hi/services/zoneminder/zm_connector.pyindex 719fb9a2..7faca9eb 100644--- a/src/hi/services/zoneminder/zm_connector.py+++ b/src/hi/services/zoneminder/zm_connector.py@@ -32,7 +32,7 @@ logger = logging.getLogger(__name__)class ZmConnector( IntegrationConnector, ZoneMinderMixin ):- def get_integration_metadata(self):+ def get_metadata(self):return ZmMetaDatadef get_monitor(self) -> ZoneMinderMonitor:@@ -180,7 +180,7 @@ class ZmConnector( IntegrationConnector, ZoneMinderMixin ):'Nodect': 'Nodect',}- def get_description(self, is_initial_connect: bool) -> Optional[str]:+ def get_sync_description(self, is_initial_connect: bool) -> Optional[str]:if is_initial_connect:return ('Each monitor becomes a camera with motion and'diff --git a/src/hi/settings/base.py b/src/hi/settings/base.pyindex cb04fe71..076361d8 100644--- a/src/hi/settings/base.py+++ b/src/hi/settings/base.py@@ -128,6 +128,7 @@ INSTALLED_APPS = ['hi.services.hass','hi.services.homebox','hi.services.frigate',+ 'hi.services.paperless','hi.apps.profiles',]@@ -292,6 +293,7 @@ PIPELINE = {'js/video-timeline.js','js/attr.js','js/attr-dirty-tracking.js',+ 'js/attr-picker.js',),'output_filename': 'js/js_hi_grid_header_content.js',},diff --git a/src/hi/settings/simulator.py b/src/hi/settings/simulator.pyindex 28e9f984..c7eb2f1b 100644--- a/src/hi/settings/simulator.py+++ b/src/hi/settings/simulator.py@@ -21,6 +21,7 @@ INSTALLED_APPS = ['hi.simulator.services.frigate','hi.simulator.services.hass','hi.simulator.services.homebox',+ 'hi.simulator.services.paperless','hi.simulator.services.zoneminder','hi.simulator.weather_sources.nws',]diff --git a/src/hi/simulator/services/paperless/__init__.py b/src/hi/simulator/services/paperless/__init__.pynew file mode 100644index 00000000..e69de29bdiff --git a/src/hi/simulator/services/paperless/apps.py b/src/hi/simulator/services/paperless/apps.pynew file mode 100644index 00000000..9745c6cf--- /dev/null+++ b/src/hi/simulator/services/paperless/apps.py@@ -0,0 +1,7 @@+from django.apps import AppConfig+++class PaperlessConfig( AppConfig ):+ default_auto_field = 'django.db.models.BigAutoField'+ name = 'hi.simulator.services.paperless'+ simulator_module_label = 'Paperless-ngx'diff --git a/src/hi/simulator/services/paperless/simulator.py b/src/hi/simulator/services/paperless/simulator.pynew file mode 100644index 00000000..b910f48b--- /dev/null+++ b/src/hi/simulator/services/paperless/simulator.py@@ -0,0 +1,127 @@+"""Paperless-ngx simulator: parametric document-search responses.++Unlike the entity-shaped simulators (HASS, HomeBox, ZoneMinder),+paperless-ngx has no 1-to-1 mapping onto HI Entities — its+contribution is the ATTRIBUTE_REFERENCE capability, which produces+TEXT attributes on existing Entity / Location records, not new+entities. So this simulator has no SimEntities and no persistent+corpus. Instead it generates synthetic search results on the fly,+shaped by a small set of operator-tunable knobs held on the+singleton:++ - result_count : how many documents each search returns (chosen+ to exercise empty / single / multi-page picker+ rendering paths)+ - mime_mix : which mime-type mix populates result rows (PDF+ only, images only, plain text only, or mixed)+ - thumbnails : whether the simulator's+ ``/api/documents/<id>/thumb/`` endpoint serves+ a thumbnail (when off, the endpoint 404s and+ the picker falls back to its icon)+ - snippets : whether each result carries a content snippet+ (exercises picker layout with / without it)+ - latency_ms : artificial latency on the documents-list+ endpoint, for surfacing any debounce or+ loading-state issues in the picker++Settings live in memory on the singleton (same lifecycle as+HomeBox's ``_api_version``) — lost on server restart, survives+SimProfile switches.+"""+from dataclasses import dataclass+from enum import Enum+from typing import Dict, List++from hi.simulator.services.base_models import SimEntityDefinition+from hi.simulator.services.service_simulator import ServiceSimulator+++class MimeMix( Enum ):+ """Which mime types populate generated search results. Drives+ the picker's thumbnail / fallback-icon path through different+ code branches."""++ PDF_ONLY = 'PDF only'+ IMAGE_ONLY = 'Images only'+ TEXT_ONLY = 'Plain text only'+ MIXED = 'Mixed'++ @classmethod+ def default(cls) -> 'MimeMix':+ return cls.MIXED++ @property+ def label(self) -> str:+ return self.value+++# Discrete result counts the operator can pick from the extras form.+# Chosen to exercise distinct picker rendering paths: empty,+# single-result, small-multi, scroll-into-view, and large-page.+RESULT_COUNT_CHOICES = ( 0, 1, 3, 10, 50 )+++@dataclass+class PaperlessSimSettings:+ """Knobs that parametrize every documents-search response. Held+ on the PaperlessSimulator singleton; ephemeral."""++ result_count : int = 3+ mime_mix : MimeMix = MimeMix.MIXED+ thumbnails : bool = True+ snippets : bool = True+ latency_ms : int = 0+++class PaperlessSimulator( ServiceSimulator ):+ """Stub paperless-ngx server. Responds to any documents query+ with a parametrically-generated result list shaped by the+ operator-tuned ``PaperlessSimSettings``."""++ def __init_singleton__( self ):+ # Set BEFORE initialize() so a SimProfile switch does NOT+ # reset operator-tuned settings (same lifecycle as+ # ``_fault_mode`` on the base class).+ self._settings = PaperlessSimSettings()+ super().__init_singleton__()+ return++ @property+ def id(self) -> str:+ return 'paperless'++ @property+ def label(self) -> str:+ return 'Paperless-ngx'++ @property+ def integration_urls(self) -> List[ tuple ]:+ return [ ( 'Paperless API base', 'services/paperless/' ) ]++ @property+ def settings(self) -> PaperlessSimSettings:+ return self._settings++ def set_settings( self, settings : PaperlessSimSettings ) -> None:+ self._settings = settings+ return++ @property+ def sim_entity_definition_list(self) -> List[ SimEntityDefinition ]:+ # Paperless contributes only via ATTRIBUTE_REFERENCE — no+ # SimEntity rows ever, so the service page's entity-list+ # area renders empty. The extras pane carries the operator+ # UI.+ return []++ @property+ def extras_template_name(self) -> str:+ return 'paperless/panes/settings_form.html'++ @property+ def extras_context(self) -> Dict:+ return {+ 'settings': self._settings,+ 'result_count_choices': RESULT_COUNT_CHOICES,+ 'mime_mix_choices': list( MimeMix ),+ }diff --git a/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.html b/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.htmlnew file mode 100644index 00000000..41055134--- /dev/null+++ b/src/hi/simulator/services/paperless/templates/paperless/pages/document_preview.html@@ -0,0 +1,17 @@+<!DOCTYPE html>+<html lang="en">+<head>+ <meta charset="utf-8">+ <title>Paperless-ngx Simulator — Document #{{ document_id }}</title>+ <style>+ body { font-family: sans-serif; max-width: 40em; margin: 4em auto; color: #212529; }+ .doc-id { font-size: 3em; color: #6c757d; }+ .hint { color: #6c757d; margin-top: 2em; font-size: 0.9em; }+ </style>+</head>+<body>+ <div class="doc-id">Document #{{ document_id }}</div>+ <p>This is the paperless-ngx simulator's stand-in for the per-document view. The real paperless web UI would show the document's metadata and content here.</p>+ <p class="hint">Source URLs from the ATTRIBUTE_REFERENCE picker link to pages like this one; close the tab to return to the picker modal.</p>+</body>+</html>diff --git a/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.html b/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.htmlnew file mode 100644index 00000000..069e16d4--- /dev/null+++ b/src/hi/simulator/services/paperless/templates/paperless/panes/settings_form.html@@ -0,0 +1,101 @@+{% comment %}+ Operator-tuned knobs for the paperless-ngx simulator's parametric+ search response. Each control submits the form on change (no+ submit button) so toggles take effect immediately, in the same+ style as the HomeBox API-version pane.++ Antinode: the form posts back to itself via data-async and the+ view returns the same template fragment, so the pane swaps in+ place with no page reload.++ Context:+ settings : PaperlessSimSettings+ result_count_choices : tuple[int]+ mime_mix_choices : list[MimeMix]+{% endcomment %}+<form id="hi-paperless-settings-form"+ method="post"+ action="{% url 'paperless_settings_set' %}"+ class="mb-3"+ data-async data-mode="replace">+ {% csrf_token %}++ <div class="form-row align-items-end">++ <div class="form-group col-auto">+ <label for="hi-paperless-result-count" class="small text-muted mb-1">+ Result count+ </label>+ <select id="hi-paperless-result-count"+ name="result_count"+ class="form-control form-control-sm"+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">+ {% for choice in result_count_choices %}+ <option value="{{ choice }}"+ {% if choice == settings.result_count %}selected{% endif %}>+ {{ choice }}+ </option>+ {% endfor %}+ </select>+ </div>++ <div class="form-group col-auto">+ <label for="hi-paperless-mime-mix" class="small text-muted mb-1">+ Mime mix+ </label>+ <select id="hi-paperless-mime-mix"+ name="mime_mix"+ class="form-control form-control-sm"+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">+ {% for choice in mime_mix_choices %}+ <option value="{{ choice.name }}"+ {% if choice == settings.mime_mix %}selected{% endif %}>+ {{ choice.label }}+ </option>+ {% endfor %}+ </select>+ </div>++ <div class="form-group col-auto">+ <label for="hi-paperless-latency" class="small text-muted mb-1">+ Latency (ms)+ </label>+ <input type="number"+ id="hi-paperless-latency"+ name="latency_ms"+ value="{{ settings.latency_ms }}"+ min="0" max="10000" step="50"+ class="form-control form-control-sm"+ style="width: 8em;"+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">+ </div>++ <div class="form-group col-auto mb-0">+ <div class="form-check">+ <input type="checkbox"+ id="hi-paperless-thumbnails"+ name="thumbnails"+ value="on"+ class="form-check-input"+ {% if settings.thumbnails %}checked{% endif %}+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">+ <label class="form-check-label small" for="hi-paperless-thumbnails">+ Thumbnails+ </label>+ </div>+ <div class="form-check">+ <input type="checkbox"+ id="hi-paperless-snippets"+ name="snippets"+ value="on"+ class="form-check-input"+ {% if settings.snippets %}checked{% endif %}+ onchange="this.form.requestSubmit ? this.form.requestSubmit() : this.form.submit()">+ <label class="form-check-label small" for="hi-paperless-snippets">+ Snippets+ </label>+ </div>+ </div>++ </div>+</form>diff --git a/src/hi/simulator/services/paperless/urls.py b/src/hi/simulator/services/paperless/urls.pynew file mode 100644index 00000000..c406c738--- /dev/null+++ b/src/hi/simulator/services/paperless/urls.py@@ -0,0 +1,23 @@+from django.urls import path++from . import views+++urlpatterns = [++ path( 'api/documents/',+ views.DocumentsListView.as_view(),+ name = 'paperless_documents_list' ),++ path( 'api/documents/<int:document_id>/thumb/',+ views.ThumbnailView.as_view(),+ name = 'paperless_document_thumbnail' ),++ path( 'documents/<int:document_id>/details/',+ views.PreviewView.as_view(),+ name = 'paperless_document_preview' ),++ path( 'settings/set/',+ views.SetSettingsView.as_view(),+ name = 'paperless_settings_set' ),+]diff --git a/src/hi/simulator/services/paperless/views.py b/src/hi/simulator/services/paperless/views.pynew file mode 100644index 00000000..464f913c--- /dev/null+++ b/src/hi/simulator/services/paperless/views.py@@ -0,0 +1,283 @@+"""Paperless-ngx simulator views.++Three endpoint families:++ - ``DocumentsListView`` — the parametric search endpoint. The+ integration's referencer hits this for every search. Response+ shape mirrors the real paperless ``GET /api/documents/?query=q``+ (DRF pagination envelope + per-doc dict).++ - ``ThumbnailView`` and ``PreviewView`` — mirror real paperless's+ per-document endpoints so the picker's thumbnail / source-URL+ handling can be exercised. ``ThumbnailView`` 404s when the+ operator has thumbnails turned off so the picker's fallback-icon+ path runs.++ - ``SetSettingsView`` — POST target for the extras form. Mutates+ the singleton's PaperlessSimSettings and re-renders the form+ fragment (the form posts via antinode ``data-async`` so the+ extras pane swaps in place).+"""+import hashlib+import random+import time+from dataclasses import replace+from datetime import datetime, timezone+from typing import List, Optional++from django.core.exceptions import BadRequest+from django.http import HttpResponse, JsonResponse+from django.shortcuts import render+from django.views import View++from .simulator import (+ MimeMix,+ PaperlessSimSettings,+ PaperlessSimulator,+ RESULT_COUNT_CHOICES,+)+++# ---- generator ---------------------------------------------------+++_MIME_PALETTE = {+ MimeMix.PDF_ONLY: ( 'application/pdf', ),+ MimeMix.IMAGE_ONLY: ( 'image/png', 'image/jpeg' ),+ MimeMix.TEXT_ONLY: ( 'text/plain', ),+ MimeMix.MIXED: ( 'application/pdf', 'image/png', 'text/plain' ),+}++_EXTENSION_BY_MIME = {+ 'application/pdf' : 'pdf',+ 'image/png' : 'png',+ 'image/jpeg' : 'jpg',+ 'text/plain' : 'txt',+}++# Filler phrases for synthetic snippets. The query is interleaved so+# the picker's snippet rendering carries a visible breadcrumb of the+# search input.+_SNIPPET_FRAGMENTS = (+ 'Annual maintenance record for {query} including replacement schedule.',+ 'Warranty terms for {query}; refer to section 4 for exclusions.',+ 'Installation manual for the {query} unit. Calibration steps follow.',+ 'Service receipt covering parts and labor on the {query} repair.',+ 'Compliance certificate issued for the {query} system this cycle.',+)+++def _stable_document_id( query : str, index : int ) -> int:+ """Map (query, index) to a stable, distinct, positive document+ id. Different queries produce distinct ids; the same query+ repeated yields the same ids. Real paperless uses unbounded+ integer document ids, so a 7-hex-digit hash (~268M range) is a+ safe stand-in."""+ digest = hashlib.sha256( f'{query}\x00{index}'.encode() ).hexdigest()+ return int( digest[:7], 16 )+++def _pick_mime( mix : MimeMix, index : int ) -> str:+ """Deterministic per-index mime pick. Cycles through the palette+ so a multi-result page rendered with MIXED visits each type."""+ palette = _MIME_PALETTE[ mix ]+ return palette[ index % len(palette) ]+++def _generate_results(+ settings : PaperlessSimSettings, query : str,+) -> List[dict]:+ """Build ``settings.result_count`` synthetic paperless documents+ for the given query. RNG is seeded from the query so a repeated+ search returns the same set — predictable for the operator."""+ rng = random.Random( query or '' )+ now_iso = datetime.now(timezone.utc).isoformat()+ documents = []+ for index in range( settings.result_count ):+ mime_type = _pick_mime( settings.mime_mix, index )+ extension = _EXTENSION_BY_MIME[ mime_type ]+ # Document id is derived from (query, index) so different+ # queries produce distinct ids — the picker uses the resulting+ # source URL as the per-result identity, and repeating ids+ # across queries would make the picker think different docs+ # were the same. (query, index) repeats stay stable, matching+ # real paperless's "same document re-found in multiple+ # searches" behavior.+ document_id = _stable_document_id( query or '', index )+ content = (+ rng.choice( _SNIPPET_FRAGMENTS ).format( query = query or 'document' )+ if settings.snippets else ''+ )+ # Titles use a human-readable index, not the hashed id, so+ # operators see "Result 1, Result 2, ..." regardless of+ # whatever id the URL ends up with.+ title = f'{query or "document"} — Result {index + 1}'+ documents.append({+ 'id' : document_id,+ 'correspondent' : None,+ 'document_type' : None,+ 'storage_path' : None,+ 'title' : title,+ 'content' : content,+ 'tags' : [],+ 'created' : now_iso,+ 'modified' : now_iso,+ 'added' : now_iso,+ 'archive_serial_number': None,+ 'original_file_name' : f'doc-{index + 1}.{extension}',+ 'archived_file_name' : None,+ 'mime_type' : mime_type,+ 'is_shared_by_requester': False,+ 'notes' : [],+ 'custom_fields' : [],+ })+ return documents+++# ---- endpoints ---------------------------------------------------+++class DocumentsListView( View ):+ """``GET /api/documents/?query=...`` — paginated documents+ search, matching paperless-ngx's response envelope."""++ def get( self, request, *args, **kwargs ):+ simulator = PaperlessSimulator()+ settings = simulator.settings+ if settings.latency_ms > 0:+ time.sleep( settings.latency_ms / 1000.0 )+ query = request.GET.get( 'query', '' ).strip()+ results = _generate_results( settings, query )+ # Mirrors the DRF pagination envelope the real paperless+ # API uses — single page, no next/previous.+ return JsonResponse({+ 'count' : len( results ),+ 'next' : None,+ 'previous' : None,+ 'all' : [ r['id'] for r in results ],+ 'results' : results,+ })+++def _thumbnail_svg( document_id : int ) -> bytes:+ """Tiny SVG placeholder. Avoids shipping a binary thumbnail just+ so the picker can render *something* in the thumbnail slot."""+ return (+ f'<svg xmlns="http://www.w3.org/2000/svg" width="120" height="160" '+ f'viewBox="0 0 120 160">'+ f'<rect width="120" height="160" fill="#e9ecef" stroke="#adb5bd"/>'+ f'<text x="60" y="86" text-anchor="middle" font-family="sans-serif" '+ f'font-size="20" fill="#495057">#{document_id}</text>'+ f'</svg>'+ ).encode('utf-8')+++class ThumbnailView( View ):+ """``GET /api/documents/<id>/thumb/`` — serves an SVG placeholder+ when thumbnails are enabled; 404s otherwise so the picker's+ fallback-icon path can be exercised."""++ def get( self, request, *args, **kwargs ):+ simulator = PaperlessSimulator()+ if not simulator.settings.thumbnails:+ return HttpResponse( status = 404 )+ try:+ document_id = int( kwargs.get( 'document_id' ) )+ except (TypeError, ValueError):+ return HttpResponse( status = 404 )+ return HttpResponse(+ _thumbnail_svg( document_id ),+ content_type = 'image/svg+xml',+ )+++class PreviewView( View ):+ """``GET /documents/<id>/details/`` — minimal preview page+ representing the per-document view in paperless's web UI. The+ picker links here as the result's source URL."""++ TEMPLATE_NAME = 'paperless/pages/document_preview.html'++ def get( self, request, *args, **kwargs ):+ try:+ document_id = int( kwargs.get( 'document_id' ) )+ except (TypeError, ValueError):+ return HttpResponse( status = 404 )+ return render(+ request,+ self.TEMPLATE_NAME,+ { 'document_id': document_id },+ )+++class SetSettingsView( View ):+ """POST target for the extras form. Validates each field,+ updates the singleton, and re-renders the settings fragment."""++ TEMPLATE_NAME = 'paperless/panes/settings_form.html'++ def post( self, request, *args, **kwargs ):+ simulator = PaperlessSimulator()+ current = simulator.settings+ new_settings = replace(+ current,+ result_count = self._parse_result_count(+ request.POST.get( 'result_count' ), current.result_count,+ ),+ mime_mix = self._parse_mime_mix(+ request.POST.get( 'mime_mix' ),+ ),+ thumbnails = self._parse_bool(+ request.POST.get( 'thumbnails' ),+ ),+ snippets = self._parse_bool(+ request.POST.get( 'snippets' ),+ ),+ latency_ms = self._parse_latency_ms(+ request.POST.get( 'latency_ms' ), current.latency_ms,+ ),+ )+ simulator.set_settings( new_settings )+ return render(+ request,+ self.TEMPLATE_NAME,+ {+ 'settings' : new_settings,+ 'result_count_choices' : RESULT_COUNT_CHOICES,+ 'mime_mix_choices' : list( MimeMix ),+ },+ )++ @staticmethod+ def _parse_result_count( raw : Optional[str], fallback : int ) -> int:+ try:+ value = int( raw )+ except (TypeError, ValueError):+ return fallback+ if value not in RESULT_COUNT_CHOICES:+ raise BadRequest( f'Invalid result_count: {raw!r}' )+ return value++ @staticmethod+ def _parse_mime_mix( raw : Optional[str] ) -> MimeMix:+ try:+ return MimeMix[ raw ]+ except (KeyError, TypeError):+ raise BadRequest( f'Invalid mime_mix: {raw!r}' )++ @staticmethod+ def _parse_bool( raw : Optional[str] ) -> bool:+ # An unchecked checkbox is absent from the POST body, so the+ # mere presence of the field name (with any truthy value) is+ # the signal.+ return bool( raw )++ @staticmethod+ def _parse_latency_ms( raw : Optional[str], fallback : int ) -> int:+ try:+ value = int( raw )+ except (TypeError, ValueError):+ return fallback+ if value < 0 or value > 10000:+ raise BadRequest( f'latency_ms out of range: {raw!r}' )+ return valuediff --git a/src/hi/simulator/services/templates/services/pages/service.html b/src/hi/simulator/services/templates/services/pages/service.htmlindex 5b33d8b6..1231098f 100644--- a/src/hi/simulator/services/templates/services/pages/service.html+++ b/src/hi/simulator/services/templates/services/pages/service.html@@ -3,7 +3,19 @@{% block main_attrs %} data-states-url="{% url 'simulator_api_states' %}"{% endblock %}{% block tab_body %}+{% comment %}+Simulators with no SimEntity definitions are ephemeral — they can't+have entities, so profile CRUD (which only varies entity persistence),+the ADD ENTITY menu (which would be empty), and the entity list (plus+its "no entities defined" empty-state) are all gated on+``sim_entity_definition_list``. Connect-shaped simulators with zero+*current* entities still have definitions, so the {% empty %} alert+still fires for them — empty is a valid Connect test scenario.++Integration URLs and the fault-mode form remain unconditional.+{% endcomment %}<div class="d-flex align-items-center justify-content-between mb-2">+ {% if simulator.sim_entity_definition_list %}{% include "profile/panes/profile_selector.html" with module=module profile_list=profile_list current_profile=current_profile %}<div class="dropdown">@@ -26,6 +38,7 @@{% endfor %}</div></div>+ {% endif %}{% if simulator.integration_urls %}<div class="text-muted small mx-3 flex-grow-1 text-center">@@ -45,9 +58,11 @@{% include simulator.extras_template_name %}{% endif %}+{% if simulator.sim_entity_definition_list %}{% for sim_entity in simulator.sim_entities %}{% include "services/panes/sim_entity.html" with simulator=simulator sim_entity=sim_entity %}{% empty %}<div class="alert alert-info">No {{ simulator.label }} simulator entities defined.</div>{% endfor %}+{% endif %}{% endblock %}diff --git a/src/hi/static/css/attribute.css b/src/hi/static/css/attribute.cssindex 08823763..452f0a11 100644--- a/src/hi/static/css/attribute.css+++ b/src/hi/static/css/attribute.css@@ -64,13 +64,22 @@margin-left: auto; /* Push to right */}-.attr-v2-action-buttons button {+.attr-v2-action-buttons button,+.attr-v2-action-buttons a.btn {min-height: 44px; /* Touch-friendly minimum */padding: 0.375rem 0.75rem;font-size: 0.875rem;border-radius: 0.25rem;}+/* <a class="btn"> doesn't vertically center its content the way+ <button> does; force-center so anchor-styled buttons line up+ with their button-element siblings in the action bar. */+.attr-v2-action-buttons a.btn {+ display: inline-flex;+ align-items: center;+}+.attr-v2-status-message {font-size: 0.875rem;color: var(--secondary-text-color);@@ -643,6 +652,7 @@/* Button Transitions */.attr-v2-action-buttons button,+.attr-v2-action-buttons a.btn,.attr-v2-file-actions button,.attr-v2-attribute-actions button,.attr-v2-reorder-controls button,@@ -651,6 +661,7 @@}.attr-v2-action-buttons button:hover,+.attr-v2-action-buttons a.btn:hover,.attr-v2-file-actions button:hover,.attr-v2-attribute-actions button:hover,.attr-v2-reorder-controls button:hover:not(:disabled),@@ -676,6 +687,7 @@/* Enhanced focus states for buttons and interactive elements */.attr-v2-action-buttons button:focus,+.attr-v2-action-buttons a.btn:focus,.attr-v2-file-actions button:focus,.attr-v2-attribute-actions button:focus,.attr-v2-reorder-controls button:focus,@@ -883,6 +895,7 @@.attr-v2-attribute-card:hover,.attr-v2-file-thumbnail:hover,.attr-v2-action-buttons button:hover,+ .attr-v2-action-buttons a.btn:hover,.attr-v2-file-actions button:hover,.attr-v2-attribute-actions button:hover {transform: none;@@ -906,6 +919,7 @@.attr-v2-file-card,.attr-v2-attribute-card,.attr-v2-action-buttons button,+ .attr-v2-action-buttons a.btn,.attr-v2-file-actions button,.attr-v2-attribute-actions button,.attr-v2-reorder-controls button,@@ -984,7 +998,8 @@vertical-align: middle;}-.attr-v2-action-buttons button .hi-icon-left {+.attr-v2-action-buttons button .hi-icon-left,+.attr-v2-action-buttons a.btn .hi-icon-left {margin-right: 0.5rem;}}@@ -1742,3 +1757,70 @@padding-left: 0;}+/* ====================================================================== */+/* ATTRIBUTE_REFERENCE picker */+/* ====================================================================== */++/* Bootstrap's modal-dialog-scrollable shrinks the flex children of+ modal-content to fit the constrained height. The default Bootstrap+ markup has .modal-header / .modal-footer with flex-shrink:0 so only+ .modal-body shrinks; this project uses .modal-title in place of+ .modal-header, so we re-establish the contract here for any modal+ that opts into scrollable behavior. */+.modal-dialog-scrollable .modal-title,+.modal-dialog-scrollable .modal-footer {+ flex-shrink: 0;+}++/* The picker modal opts into Bootstrap's modal-dialog-scrollable so the+ modal-body is the scroll container while the header and footer stay+ anchored. Pin the search controls to the top edge of the body so the+ operator can refine their query at any scroll position without+ scrolling back up to find the search row. */+.hi-attr-picker-search-form {+ position: sticky;+ top: 0;+ z-index: 1;+ background-color: var(--background-color, #fff);+ padding-top: 0.5rem;+ padding-bottom: 0.5rem;+}++/* Zero the modal-body's top padding so the sticky search form is flush+ against the title — otherwise modal-body's default padding-top shows+ scrolling content through the gap above the sticky element. The+ search form supplies its own padding-top for breathing room. */+.hi-attr-picker .modal-body {+ padding-top: 0;+}++/* Source banner — always rendered. With one source the button is+ disabled (no caret, no hover affordance) so the visual matches+ the multi-source case structurally but doesn't invite a click+ that does nothing useful. The button face shows the source's+ logo on a light background; native logos meant for white render+ correctly here. */+.hi-attr-picker-source-banner {+ background-color: #fff;+ border: 1px solid var(--line-color, #dee2e6);+ padding: 0.5rem 0.75rem;+}+.hi-attr-picker-source-banner-logo {+ max-height: 24px;+ width: auto;+}+.hi-attr-picker-source-banner-label {+ font-weight: 500;+}+.hi-attr-picker-source-banner-single .dropdown-toggle::after {+ display: none;+}+.hi-attr-picker-source-banner-single .dropdown-toggle:disabled {+ opacity: 1;+ cursor: default;+}+.hi-attr-picker-source-option img {+ max-height: 20px;+ width: auto;+}+diff --git a/src/hi/static/img/integrations/paperless.png b/src/hi/static/img/integrations/paperless.pngnew file mode 100644index 00000000..718d2d86Binary files /dev/null and b/src/hi/static/img/integrations/paperless.png differdiff --git a/src/hi/static/js/attr-picker.js b/src/hi/static/js/attr-picker.jsnew file mode 100644index 00000000..d1eb8fcc--- /dev/null+++ b/src/hi/static/js/attr-picker.js@@ -0,0 +1,292 @@+/*+ * Home Information - Attribute-reference picker UI state+ *+ * Multi-select picker for ATTRIBUTE_REFERENCE integrations (e.g.,+ * paperless-ngx). The picker lets the operator search an upstream+ * source and accumulate a set of references (title + URL) across+ * multiple searches, then commit the whole set as TEXT attributes+ * in one final submit.+ *+ * Responsibilities owned by this module:+ *+ * - Hold the current attribute-selection set in JS state, keyed+ * by picker-DOM-node so multiple modals would not collide.+ * - Render the chip row from that state. Chips are the only HTML+ * this module generates; everything else is server-rendered.+ * - Update the Add button's label and enabled state to reflect+ * the current selection count.+ * - Drive an async Search request: POST query parameters, receive+ * result-cards HTML, swap into the results container. After+ * swap, re-apply checkbox state to any newly-visible result+ * whose URL is already in the selection set.+ * - On Add submit: serialize the selection set into the hidden+ * ``selections_json`` input and POST through antinode's public+ * API (``AN.hideModalIfNeeded`` + ``AN.post``) so the modal+ * close and the ``{refresh: true}`` response flow through the+ * framework.+ *+ * Handlers are delegated at the document level so dynamically-+ * inserted modal content (the antinode-loaded picker body) wires+ * up automatically — no per-modal init step. State is lazily+ * created per picker DOM node and garbage-collected when the+ * modal is removed.+ *+ * DOM classes, data-attribute names, and wire-format field names+ * all come from ``Hi.ATTR_PICKER_*`` in ``main.js``, mirrored+ * server-side in ``hi.constants.DIVID``.+ */+(function() {+ 'use strict';++ const EventNs = '.attr-picker';++ // Per-picker selection state, keyed by the picker-root DOM node+ // so multiple open modals would not collide. State is lazily+ // created on first access and garbage-collected when the modal+ // element is removed.+ const _stateByPicker = new WeakMap();++ function _state(pickerRoot) {+ let state = _stateByPicker.get(pickerRoot);+ if (!state) {+ state = { attrSelections: [] };+ _stateByPicker.set(pickerRoot, state);+ }+ return state;+ }++ function _classSelector(className) {+ return '.' + className;+ }++ function _hasSelection(state, sourceUrl) {+ const key = Hi.ATTR_PICKER_SELECTION_URL_KEY;+ return state.attrSelections.some(s => s[key] === sourceUrl);+ }++ function _addSelection(state, title, sourceUrl) {+ if (_hasSelection(state, sourceUrl)) return;+ const record = {};+ record[Hi.ATTR_PICKER_SELECTION_TITLE_KEY] = title;+ record[Hi.ATTR_PICKER_SELECTION_URL_KEY] = sourceUrl;+ state.attrSelections.push(record);+ }++ function _removeSelection(state, sourceUrl) {+ const key = Hi.ATTR_PICKER_SELECTION_URL_KEY;+ state.attrSelections = state.attrSelections.filter(+ s => s[key] !== sourceUrl+ );+ }++ function _renderChips($pickerRoot, state) {+ const $chipsContainer = $pickerRoot.find(+ _classSelector(Hi.ATTR_PICKER_CHIPS_CLASS)+ );+ const $emptyHint = $pickerRoot.find(+ _classSelector(Hi.ATTR_PICKER_CHIPS_EMPTY_CLASS)+ );+ $chipsContainer.empty();+ if (state.attrSelections.length === 0) {+ $emptyHint.removeClass('d-none');+ return;+ }+ $emptyHint.addClass('d-none');+ const titleKey = Hi.ATTR_PICKER_SELECTION_TITLE_KEY;+ const urlKey = Hi.ATTR_PICKER_SELECTION_URL_KEY;+ state.attrSelections.forEach(function(sel) {+ const $chip = $('<span>')+ .addClass('badge badge-secondary mr-2 mb-2 d-inline-flex align-items-center');+ $('<span>')+ .addClass('mr-1 text-truncate')+ .css('max-width', '220px')+ .attr('title', sel[titleKey])+ .text(sel[titleKey])+ .appendTo($chip);+ $('<button type="button">')+ .addClass('btn btn-link btn-sm p-0 text-white ml-1')+ .addClass(Hi.ATTR_PICKER_CHIP_REMOVE_CLASS)+ .attr('title', 'Remove from selection')+ .attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR, sel[urlKey])+ .text('×') // ×+ .appendTo($chip);+ $chipsContainer.append($chip);+ });+ }++ function _renderAttachButton($pickerRoot, state) {+ const count = state.attrSelections.length;+ const $btn = $pickerRoot.find(+ _classSelector(Hi.ATTR_PICKER_ATTACH_BTN_CLASS)+ );+ const noun = count === 1 ? 'Link' : 'Links';+ const $label = $btn.find(+ _classSelector(Hi.ATTR_PICKER_ATTACH_LABEL_CLASS)+ );+ const text = 'Add ' + count + ' ' + noun;+ if ($label.length) {+ $label.text(text);+ } else {+ $btn.text(text);+ }+ $btn.prop('disabled', count === 0);+ }++ function _renderAll($pickerRoot, state) {+ _renderChips($pickerRoot, state);+ _renderAttachButton($pickerRoot, state);+ }++ function _syncCheckboxesToState($pickerRoot, state) {+ $pickerRoot.find(+ _classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS)+ ).each(function() {+ const $cb = $(this);+ const sourceUrl = $cb.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);+ if (sourceUrl == null) return;+ $cb.prop('checked', _hasSelection(state, sourceUrl));+ });+ }++ // ---- Delegated handlers ------------------------------------++ $(document).on(+ 'change' + EventNs,+ _classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS),+ function() {+ const $cb = $(this);+ const $pickerRoot = $cb.closest(+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)+ );+ if ($pickerRoot.length === 0) return;+ const state = _state($pickerRoot[0]);+ const title = $cb.attr(Hi.ATTR_PICKER_TITLE_ATTR);+ const sourceUrl = $cb.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);+ if (sourceUrl == null) return;+ if ($cb.is(':checked')) {+ _addSelection(state, title, sourceUrl);+ } else {+ _removeSelection(state, sourceUrl);+ }+ _renderAll($pickerRoot, state);+ }+ );++ $(document).on(+ 'click' + EventNs,+ _classSelector(Hi.ATTR_PICKER_CHIP_REMOVE_CLASS),+ function() {+ const $btn = $(this);+ const $pickerRoot = $btn.closest(+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)+ );+ if ($pickerRoot.length === 0) return;+ const sourceUrl = $btn.attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR);+ if (sourceUrl == null) return;+ const state = _state($pickerRoot[0]);+ _removeSelection(state, sourceUrl);+ // Uncheck any visible result card whose URL matches.+ $pickerRoot+ .find(_classSelector(Hi.ATTR_PICKER_RESULT_CHECKBOX_CLASS))+ .filter(function() {+ return $(this).attr(Hi.ATTR_PICKER_SOURCE_URL_ATTR) === sourceUrl;+ })+ .prop('checked', false);+ _renderAll($pickerRoot, state);+ }+ );++ $(document).on(+ 'submit' + EventNs,+ _classSelector(Hi.ATTR_PICKER_SEARCH_FORM_CLASS),+ function(e) {+ e.preventDefault();+ const $form = $(this);+ const $pickerRoot = $form.closest(+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)+ );+ if ($pickerRoot.length === 0) return;+ const searchUrl = $form.attr(Hi.ATTR_PICKER_SEARCH_URL_ATTR);+ $.ajax({+ url: searchUrl,+ method: 'POST',+ data: $form.serialize(),+ headers: { 'X-Requested-With': 'XMLHttpRequest' }+ }).done(function(html) {+ $pickerRoot.find(+ _classSelector(Hi.ATTR_PICKER_RESULTS_CLASS)+ ).html(html);+ _syncCheckboxesToState($pickerRoot, _state($pickerRoot[0]));+ });+ }+ );++ $(document).on(+ 'submit' + EventNs,+ _classSelector(Hi.ATTR_PICKER_ATTACH_FORM_CLASS),+ function(e) {+ // Own the submit lifecycle so the in-memory selection set+ // is populated into the hidden input BEFORE the form is+ // read. The form deliberately omits ``data-async`` so+ // antinode's body-level submit handler doesn't race us —+ // we instead route through antinode's public API (modal+ // close + POST) so the ``{refresh: true}`` response and+ // the modal cleanup still flow through the framework.+ e.preventDefault();+ const $form = $(this);+ const $pickerRoot = $form.closest(+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)+ );+ if ($pickerRoot.length === 0) return;+ const state = _state($pickerRoot[0]);+ const fieldName = Hi.ATTR_PICKER_SELECTIONS_JSON_FIELD;+ $form.find('input[name="' + fieldName + '"]')+ .val(JSON.stringify(state.attrSelections));+ if (!window.AN) {+ // Defensive: antinode is part of the base bundle, but+ // if it ever fails to load we fall back to a plain+ // submit so the operator's click is not lost.+ $form[0].submit();+ return;+ }+ window.AN.hideModalIfNeeded($form[0]);+ window.AN.post($form.attr('action'), $form.serialize());+ }+ );++ $(document).on(+ 'click' + EventNs,+ _classSelector(Hi.ATTR_PICKER_SOURCE_OPTION_CLASS),+ function(e) {+ // Switch the active source: update the banner face, set+ // the hidden integration_id input, and re-issue the+ // current search against the new source. Selections+ // already in state stay put — they're keyed by URL, not+ // by source.+ e.preventDefault();+ const $option = $(this);+ const $pickerRoot = $option.closest(+ _classSelector(Hi.ATTR_PICKER_ROOT_CLASS)+ );+ if ($pickerRoot.length === 0) return;+ const sourceId = $option.attr(Hi.ATTR_PICKER_SOURCE_ID_ATTR);+ const sourceLogo = $option.attr(Hi.ATTR_PICKER_SOURCE_LOGO_ATTR);+ const sourceLabel = $option.attr(Hi.ATTR_PICKER_SOURCE_LABEL_ATTR);+ if (sourceId == null) return;+ $pickerRoot+ .find(_classSelector(Hi.ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS))+ .attr('src', sourceLogo);+ $pickerRoot+ .find(_classSelector(Hi.ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS))+ .text(sourceLabel);+ const fieldName = Hi.ATTR_PICKER_INTEGRATION_ID_FIELD;+ $pickerRoot+ .find('input[name="' + fieldName + '"]')+ .val(sourceId);+ $pickerRoot+ .find(_classSelector(Hi.ATTR_PICKER_SEARCH_FORM_CLASS))+ .trigger('submit');+ }+ );++})();diff --git a/src/hi/static/js/attr.js b/src/hi/static/js/attr.jsindex a80ea488..28935999 100644--- a/src/hi/static/js/attr.js+++ b/src/hi/static/js/attr.js@@ -172,7 +172,8 @@_updateOrderIndexes($container);}- const formData = new FormData($form[0]);+ const submitter = options.submitter || null;+ const formData = new FormData($form[0], submitter);const url = $form.attr('action');const method = $form.attr('method') || 'POST';@@ -649,8 +650,13 @@// Add custom Ajax submission handler$form.on(`submit.${ATTR_V2_INTERNAL.AJAX_EVENT_NAMESPACE}`, function(e) {e.preventDefault();-- _ajax.submitFormWithAjax(form);++ // Pass the submitter so the clicked button's name/value+ // is included in FormData — matches native browser+ // behavior for multi-submit-button forms (e.g., a form+ // with both SAVE and DISABLE buttons).+ const submitter = (e.originalEvent && e.originalEvent.submitter) || null;+ _ajax.submitFormWithAjax(form, { submitter });});});diff --git a/src/hi/static/js/main.js b/src/hi/static/js/main.jsindex cf8c6870..5588e643 100644--- a/src/hi/static/js/main.js+++ b/src/hi/static/js/main.js@@ -160,7 +160,40 @@ENTITY_PICKER_STATUS_UNUSED: 'unused',// Entity Picker - Filter values- ENTITY_PICKER_FILTER_ALL: 'all'+ ENTITY_PICKER_FILTER_ALL: 'all',++ // ATTRIBUTE_REFERENCE picker — DOM classes / data attributes+ // / wire-format field names shared with the server. Mirror+ // of the ``ATTR_PICKER_*`` entries in+ // ``src/hi/constants.py:DIVID``.+ ATTR_PICKER_ROOT_CLASS: 'hi-attr-picker',+ ATTR_PICKER_CHIPS_CLASS: 'hi-attr-picker-chips',+ ATTR_PICKER_CHIPS_EMPTY_CLASS: 'hi-attr-picker-chips-empty',+ ATTR_PICKER_CHIP_REMOVE_CLASS: 'hi-attr-picker-chip-remove',+ ATTR_PICKER_RESULTS_CLASS: 'hi-attr-picker-results',+ ATTR_PICKER_SEARCH_FORM_CLASS: 'hi-attr-picker-search-form',+ ATTR_PICKER_ATTACH_FORM_CLASS: 'hi-attr-picker-attach-form',+ ATTR_PICKER_ATTACH_BTN_CLASS: 'hi-attr-picker-attach-btn',+ ATTR_PICKER_ATTACH_LABEL_CLASS: 'hi-attr-picker-attach-label',+ ATTR_PICKER_RESULT_CHECKBOX_CLASS: 'hi-attr-picker-result-checkbox',+ ATTR_PICKER_SEARCH_URL_ATTR: 'data-attr-picker-search-url',+ ATTR_PICKER_TITLE_ATTR: 'data-attr-picker-title',+ ATTR_PICKER_SOURCE_URL_ATTR: 'data-attr-picker-source-url',+ ATTR_PICKER_QUERY_FIELD: 'query',+ ATTR_PICKER_LIMIT_FIELD: 'limit',+ ATTR_PICKER_ITEM_TYPE_FIELD: 'item_type',+ ATTR_PICKER_ITEM_ID_FIELD: 'item_id',+ ATTR_PICKER_INTEGRATION_ID_FIELD: 'integration_id',+ ATTR_PICKER_SELECTIONS_JSON_FIELD: 'selections_json',+ ATTR_PICKER_SELECTION_TITLE_KEY: 'title',+ ATTR_PICKER_SELECTION_URL_KEY: 'source_url',+ ATTR_PICKER_SOURCE_BANNER_CLASS: 'hi-attr-picker-source-banner',+ ATTR_PICKER_SOURCE_BANNER_LOGO_CLASS: 'hi-attr-picker-source-banner-logo',+ ATTR_PICKER_SOURCE_BANNER_LABEL_CLASS: 'hi-attr-picker-source-banner-label',+ ATTR_PICKER_SOURCE_OPTION_CLASS: 'hi-attr-picker-source-option',+ ATTR_PICKER_SOURCE_ID_ATTR: 'data-attr-picker-source-id',+ ATTR_PICKER_SOURCE_LOGO_ATTR: 'data-attr-picker-source-logo',+ ATTR_PICKER_SOURCE_LABEL_ATTR: 'data-attr-picker-source-label'};window.Hi = Hi;diff --git a/src/hi/templates/icons/link.html b/src/hi/templates/icons/link.htmlnew file mode 100644index 00000000..6e7feaf7--- /dev/null+++ b/src/hi/templates/icons/link.html@@ -0,0 +1,3 @@+<svg class="{{ class_attr }}" viewBox="0 0 24 24" fill="currentColor" {{ accessibility_attrs }}>+ <path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76 0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71 0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71 0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76 0 5-2.24 5-5s-2.24-5-5-5z"/>+</svg>