=== Garagem ===
Contributors: crmgaragem
Tags: real estate, crm, property management, realtor, whatsapp
Requires at least: 6.0
Tested up to: 7.1
Stable tag: 1.1.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect WordPress to Garagem CRM for property search, listing and detail pages, plus seller lead forms with automatic synchronization.

== Description ==

**Garagem** connects WordPress to [Garagem CRM](https://garagem.ai) so you can publish property search/listing pages, property detail pages, and seller lead flows with real-time synchronization.

It is compatible with standard WordPress themes and page builders (including Gutenberg, Elementor, and Divi), and supports server-side rendering for crawlable HTML output.

= Why use Garagem? =

**Setup and synchronization**

* **Fast setup** — Install, configure your Site ID, add a shortcode, and publish listings without custom code
* **Near real-time updates** — Property updates in Garagem CRM are reflected on the site
* **Theme compatibility** — Responsive UI that integrates with common WordPress themes/builders
* **Caching support** — Uses minified assets and works with common cache plugins

**Search and navigation**

* **Advanced filters** — Filter by listing type, property type, bedrooms, price range, area, and more
* **Carousel mode** — Display highlighted listings with horizontal navigation
* **Configurable display** — Control grid density, primary color, and display mode via shortcode attributes

**Property pages**

* **Individual property URLs** — Detail pages with media, metadata, and lead forms
* **SEO-ready output** — Server-rendered HTML plus JSON-LD and Open Graph metadata
* **Related properties** — Similar listings support to improve navigation

**Lead capture**

* **Integrated forms** — Contact/visit forms and seller lead flow connected to Garagem CRM
* **WhatsApp workflow support** — Designed to fit CRM workflows that include WhatsApp communication

= Quick start =

1. Install and activate the plugin
2. Go to Settings → Garagem
3. Configure your Site ID (Garagem CRM → Settings → Channels → Sites)
4. Add a shortcode to any page:
   - `[garagem_search]` (search/listing)
   - `[garagem_property code="145242"]` (single property page)
   - `[garagem_seller_lead]` (seller lead flow)

= Shortcodes =

* `[garagem_search]` — Search form + property grid
* `[garagem_property code="145242"]` — Full page for a specific property
* `[garagem_seller_lead]` — Seller lead capture flow

= Shortcode attributes =

**[garagem_search]**

* `layout` — Grid density: `confortavel` (default), `compacto`, `denso`, `ultra-denso`
* `limit` — Properties per page (default: 12)
* `display` — `grid` (default) or `carousel`
* `property_click` — `detail` (default, drawer) or `page` (property page)
* `hide_search` — `true` to hide the search bar
* `new_tab` — `true` to open links in a new tab

**[garagem_seller_lead]**

* `photo_module` — `enabled` or `disabled`
* `photo_modes` — CSV options: `upload,schedule,later`
* `schedule_disabled_days` — CSV blocked days (`0-6`)
* `weekday_time_slots` — CSV time slots for weekdays
* `weekend_time_slots` — CSV time slots for weekends
* `property_fields` — CSV for step-2 fields (example: `saleValue:required`)
* `background_color` — Background color (hex)
* `text_color` — Text color (hex)

= About Garagem =

[Garagem](https://garagem.ai) is a real estate CRM platform for agents and brokerages.

Learn more: [Garagem website](https://garagem.ai) | [Plugin documentation](https://docs.garagem.ai/integracoes/plugin-wordpress)

= Requirements =

* An active [Garagem CRM](https://garagem.ai) account (paid service) with at least one published site — this plugin depends on Garagem API services
* PHP 7.4 or newer
* WordPress 6.0 or newer

= For developers =

Source code and build tooling are available at:
[https://github.com/emcasa/garagem/tree/main/apps/site/wordpress-plugin](https://github.com/emcasa/garagem/tree/main/apps/site/wordpress-plugin)

The plugin includes both minified assets (`assets/`) and non-minified source files (`src/`) for review. Minification is built with esbuild and keeps identifiers readable (no mangling).

**Visual customization:** all plugin CSS classes use the `.garagem-` prefix and can be overridden in your theme CSS or a custom CSS plugin, without editing plugin files.

**Compatibility:** the plugin uses standard WordPress enqueue APIs (`wp_enqueue_scripts`, `wp_enqueue_style`) and is designed to avoid conflicts with themes/plugins. Shortcodes work in any shortcode-enabled context, including Elementor (HTML/Shortcode widget), Divi (Text/Code module), and the Block Editor (Shortcode block).

== External services ==

This plugin connects to the **Garagem Sites API** to display property listings on your WordPress site. The default API origin is `https://cdn.fndn.ai`. A saved endpoint of `https://app.garagem.ai/api/sites` is upgraded to that default automatically. An explicit custom endpoint in Settings is left unchanged.

This service is provided by **Garagem** (https://garagem.ai).

**What the service is and what it is used for:**

The Garagem Sites API provides real estate listing data. Requests use the base `https://cdn.fndn.ai/site/api/sites`:

* Fetch site configuration (branding, URL patterns) — `GET /resolve?siteId={siteId}`
* Fetch search results with filters and pagination — `POST /{siteId}/search`
* Fetch individual property details — `GET /{siteId}/property/{id}`
* Fetch available locations for the filter UI — `GET /{siteId}/locations`
* Receive contact, visit, and seller-lead submissions — `POST /api/webhooks/sites/{siteId}/leads` on the same origin
* Receive property photo uploads from the seller lead flow — `POST /api/webhooks/sites/{siteId}/photos` on the same origin

The `[garagem_seller_lead]` shortcode also loads a map for address entry:

* By default it loads `https://maps.fndn.ai/sdk.js` (Garagem Maps). No Google API key is sent.
* If a Google Maps API key is saved in Settings → Garagem, that loader is replaced by `https://maps.googleapis.com/maps/api/js` and the key is sent to Google as the `key` query parameter.

**What data is sent and when:**

* **On every page load** containing a plugin shortcode: your Garagem Site ID, search parameters entered by visitors (text query, filters, pagination), and property codes when viewing individual properties. Responses are cached with WordPress Transients: search for 1 minute, site configuration and property details for 5 minutes, locations for 30 minutes.
* **On a seller-lead page:** the browser loads `https://maps.fndn.ai/sdk.js`, or Google Maps JavaScript when a key is configured. Address text the visitor types is sent to that map service for autocomplete.
* **On voluntary form submission only:** name, email, phone, message, address, property metadata, optional visit date/time, and optional photos. No visitor-identifiable data is sent unless the visitor submits a form.

**No tracking:** The plugin does not set cookies, does not collect visitor analytics, and does not fingerprint visitors.

* **Service URL**: https://cdn.fndn.ai/site/api/sites
* **Maps URL**: https://maps.fndn.ai/sdk.js
* **Terms of Use**: https://garagem.ai/termos
* **Privacy Policy**: https://garagem.ai/privacidade

== Installation ==

1. Upload the `garagem` folder to `/wp-content/plugins/` (or upload the ZIP from Plugins → Add New)
2. Activate the plugin from the Plugins screen
3. Go to Settings → Garagem
4. Configure your Site ID (Garagem CRM → Configurações → Canais → Sites)
5. Click "Testar conexão" to validate connectivity
6. Add shortcodes to your pages

== Frequently Asked Questions ==

= Where can I find my Site ID? =

In Garagem CRM, go to Configurações → Canais → Sites, select your site, and copy the Site ID shown in the WordPress Plugin section.

= How fast do changes sync? =

Search results are cached for 1 minute, site configuration and property details for 5 minutes, and locations for 30 minutes. Those times are fixed in the plugin. The Cache duration field in Settings → Garagem applies only when a response is stored without its own TTL. Use **Limpar cache** after a CRM change if you need the site to update immediately.

= Does it work with my theme? =

Yes. The plugin uses a responsive grid that adapts to standard WordPress themes. You can further customize appearance by defining the primary color in Settings → Garagem and overriding `.garagem-` classes in your theme CSS.

= Can visitors search and filter properties? =

Yes. The plugin includes a search bar and filters for property type, bedrooms, price range, area, and more. Visitors can also sort results by relevance, price, or area, and use grid or carousel display modes.

= Does each property have its own page? =

Yes. When enabled in plugin settings, the plugin generates individual property pages with gallery, description, metadata, and contact actions based on CRM data.

= Does the plugin work without JavaScript? =

Yes. Core content is server-rendered in HTML. Property cards, images, prices, and pagination work without JavaScript. Enhanced interactions (fullscreen gallery, filter modal, lead dialogs) are added when JavaScript is available.

= Do I need a Garagem account? =

Yes. You need an active [Garagem CRM](https://garagem.ai) account with at least one published site.

= Is the plugin compatible with LGPD/GDPR? =

The plugin does not track visitors (no analytics cookies or passive personal-data collection). It requests public listing data from Garagem API and sends personal data only when a visitor explicitly submits a contact/visit/seller-lead form.

= Can I show properties in carousel format? =

Yes. Use `[garagem_search display="carousel"]` to render a horizontal carousel.

= Does the plugin support Brazilian Portuguese? =

Yes. The plugin ships with Brazilian Portuguese (`pt_BR`) translations for interface labels and messages.

= Do I need to code to use it? =

No. Setup is done in the WordPress admin (Settings → Garagem). After setting your Site ID, add `[garagem_search]` to any page.

= Does it work with Elementor, Divi, and Gutenberg? =

Yes. Shortcodes work in any shortcode-enabled builder/editor, including Elementor, Divi, and the Block Editor.

= Can this plugin slow down my site? =

The plugin is optimized for production with minified assets and transient caching for API responses. It is compatible with common cache plugins.

= Can I customize colors and visual styles? =

Yes. You can define a primary color in Settings → Garagem and override `.garagem-` classes in your theme CSS.

== Screenshots ==

1. Property search page with grid, sorting, and filter bar
2. Search page with advanced filter panel open
3. Featured properties carousel with horizontal navigation
4. Individual property page with details, gallery, and lead capture
5. Property detail drawer opened from search results
6. Fullscreen gallery with navigation controls
7. Plugin settings page in WordPress admin

== Changelog ==

= 1.1.0 =
* Property URLs follow public-site routing: when the tenant lists both sale and rental, links include `/venda` or `/aluguel`, unless `includeListingType` is false or unified listing detail is on
* New shortcode `[garagem_seller_lead]` for the list-your-property flow, including optional photo upload
* API base is `https://cdn.fndn.ai/site/api/sites`. A stored `https://app.garagem.ai/api/sites` value is upgraded automatically
* Lead and photo submissions go to `/api/webhooks/sites/{siteId}/leads` and `/photos`
* Seller-lead address map loads `https://maps.fndn.ai/sdk.js` unless a Google Maps API key is set

= 1.0.1 =
* Plugin name shown as **Garagem** (previously Garagem Properties)
* Directory tags aligned: real estate, crm, property management, realtor, whatsapp
* Updated readme copy and settings references (Configurações → Garagem)

= 1.0.0 =
* Initial release
* Server-rendered property listing visible without JavaScript
* Progressive enhancement: gallery, filters, and lead capture via JavaScript
* Property search with filters, sorting, and configurable grid layout
* Individual property pages with gallery, metadata, and contact form
* Carousel mode for featured listings
* Admin settings page with connection test
* SEO support: Open Graph tags, JSON-LD structured data, crawlable HTML
* WordPress Transients caching
* `SCRIPT_DEBUG` support for development
* Brazilian Portuguese (`pt_BR`) translation support
* Source files included alongside minified assets for review

== Upgrade Notice ==

= 1.1.0 =
Property URLs can include `/venda` or `/aluguel`. Adds the seller-lead shortcode and sends listings, leads, and the address map through cdn.fndn.ai and maps.fndn.ai.

= 1.0.1 =
Branding and metadata update. No breaking changes.

= 1.0.0 =
Initial release. Publish Garagem CRM properties with server rendering, search, and SEO support.
