=== Flexa Local Services ===
Contributors: flexatech
Tags: local business, booking, appointments, leads, services
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.1.4
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Service pages, online booking and a lead form for a local business, with optional CRM, payments, reviews and analytics modules.

== Description ==

A plumber's website usually ends up running three plugins: one for the contact form, one to lay out services and testimonials, one for local business schema. None of them knows about the others. So the alert that lands in the owner's inbox says a form was submitted, and leaves out the thing they actually want to know, which job the caller is asking about.

Flexa Local Services is those three jobs in one plugin, wired together. The form knows which page it was sitting on, so every lead arrives labelled "Emergency Plumbing" or "Drain Cleaning" rather than "Contact form". Hitting reply on the alert email goes to the customer, not to the website. Both of those are small things that decide whether the owner keeps the plugin after week one.

Everything lives under one **Flexa Local** menu: the content you publish, the leads that come in, the forms that collect them, and the settings they share. When the business outgrows a contact form, the same menu has modules for online booking, customers, payments, reviews and more. They ship inside the plugin and stay off until you switch them on.

= What you get on day one =

* A setup checklist on the dashboard that tracks five real steps and does not tick itself.
* A starter site for nine trades, so one click fills an empty plugin with example content you can edit.
* Leads listed newest first, with the page, the phone number and the email on the same row.
* Reply and Call buttons on each lead, so the follow-up happens from a phone.
* Email alerts that quote the visitor's own answers under the question they were asked.
* CSV export, with a UTF-8 marker so Excel reads accented names correctly, and spreadsheet formulas defused so an export cannot run anything on your machine.

= A starter site, if you want one =

An empty plugin is hard to judge. Pick a trade on the Tools screen, press Import, and you get a worked example of a whole site: home, services, pricing, service areas, recent work, reviews, about, FAQ, contact and a quote page, each one assembled from the blocks. Plumbing, electrical, HVAC, roofing and locksmith get an emergency call-out page as well, because those are the trades whose customers go looking for one at midnight.

Behind the pages sit six services with starting prices, six service areas, six testimonials, eight FAQs, three team members, three finished jobs, three offers and a quote form wired to the leads table.

Nine trades are there to pick from: plumbing, electrical, HVAC, roofing, locksmith, appliance repair, pest control, cleaning and landscaping. Everything is sample text about an invented company in Portland, written to be plausible rather than impressive, so edit the prices and the phone number before you launch. No images are bundled.

The pages arrive as drafts, so nothing shows up on your site until you publish them.

Publishing is one tick, and two more sit next to it: Home becomes the front page of the site, and a navigation menu is built from the page set and hung in the first free slot your theme offers. Both are on by default, and both need the pages published, so they sit out an import that comes in as drafts. The company name, phone, email and address are filled in from the sample data either way, but only where you have not set them yet. Nothing you already filled in is overwritten, and a menu your theme is already showing is left where it is. On a block theme the menu is still created, ready to drop into a Navigation block.

One button on the same screen takes the whole import back out again, by ID. The front page setting and the menu location go back the way they were, anything you edited in the meantime is kept, and no lead is ever touched.

= Content types =

Each one is a normal WordPress post type, so the editor, revisions, featured images and search all behave the way you expect.

* **Services** with a starting price, hero text, a call to action and optional JSON-LD schema
* **Service areas** with city, state, ZIP codes and coordinates, so visitors can tell whether you cover them
* **Projects** for finished work, with before and after images, cost, duration and the service and area they belong to
* **Testimonials** with a star rating, the customer's name, a photo and an optional video
* **Team** members with a role, years of experience, phone, email and photo
* **FAQs**, grouped by category and attachable to a service
* **Coupons** with a code, a fixed or percentage discount and an expiry date

= Blocks =

Twelve blocks render your content on the front end. They are server rendered, so a published page always shows the current data, not a copy frozen at the time you saved it.

Services Grid, Areas Grid, Projects, Testimonials, Team, FAQ, Coupons, Pricing, Hero, CTA, Contact Card and Form.

= Lead capture =

Build a form in the Forms screen, drop the Form block (or the `[flexa_local_form id="1"]` shortcode) on any page, and submissions land in the Leads screen.

* Each lead records the page it came from, which is the whole point of reusing one form across a site.
* Works with JavaScript switched off. With JavaScript on, it submits without reloading the page.
* A honeypot field and a timing check reject bots, so visitors never meet a CAPTCHA.
* Email alerts to one address or several, with Reply-To set to the customer.
* Mark a lead new, contacted, won or lost.

= Modules =

Eight modules come with the plugin. Each one is off on a new site, and a module that is off runs no code at all. Switch them on and off under **Flexa Local > Modules**; turning one off keeps its data.

* **Booking**: online appointments. See below.
* **Customers (CRM)**: leads and bookings become customer records with a drag-and-drop pipeline from new to won or lost, tags, custom fields, tasks, an activity timeline, CSV import and export, and timed email sequences.
* **Payments**: manual payments and Stripe Checkout, booking deposits, full or partial refunds, receipts, taxes, recurring billing and optional PDF invoices.
* **Reviews**: a review form with up to three photos, moderation, public replies, a Reviews block with star ratings and schema.org markup, and a review request emailed after a booking.
* **Analytics**: leads, form submissions and bookings per day, conversion goals, a comparison with the previous period, which campaigns and sites bring conversions (first or last touch), CSV export and a weekly email report.
* **Membership**: paid or free plans with tiers, a Members Only block that can unlock content a set number of days after joining, WordPress roles per plan and member-only coupon codes. Paid plans need the Payments module.
* **AI Assistant**: a chat on your site that answers visitors from your own pages, services and FAQs, plus content writing, lead scoring and suggested review replies. It uses your own Anthropic (Claude) API key.
* **Mobile API**: the backend for a mobile app: token sign-in, app settings in one call, offline sync, push notification queue and app links.

= Online booking =

Switch on the Booking module and add the Booking Form block to a page. Visitors pick a service, a staff member or resource if you offer a choice, a date and a free time, and the booking arrives in the Bookings screen.

* Times already taken are never offered, so a slot cannot be booked twice.
* Business hours, plus working hours and days off for each staff member or resource.
* A calendar popup for the date, and only the times still free on that day.
* Confirmation and reminder emails, each with a calendar file attached.
* Customers cancel or reschedule from the link in their email, without an account.
* Optional repeat bookings: weekly, every two weeks or monthly.
* Change a booking's status, reschedule it or download its calendar file from the admin.
* Optional deposits through the Payments module, and optional two-way sync with Google Calendar.

= For developers =

* REST API under `fxlc/v1` for content, forms, entries, leads and settings. Each module adds its own routes to the same namespace.
* Hooks for the pieces you are most likely to want to change: `fxlc_lead_notification`, `fxlc_form_spam_check`, `fxlc_form_public_submit`, `fxlc_settings_defaults`, `fxlc_admin_menu`, `fxlc_demo_packs`, `fxlc_demo_pages` and more.
* Leads and form submissions live in their own tables, so a large volume of them never slows down your posts list.
* The core plugin uses no external services: lead emails go out through WordPress's own mail function. A few modules can talk to an outside service once you configure it; see External services below.

== Source code ==

Four files in this plugin are compiled, in two bundles:

* The main admin app: `assets/dist/assets/main-*.js` and `main-*.css`, built
  from `apps/admin/src/` (TypeScript and React).
* The Booking module's admin screen: `addons/booking/assets/dist/admin.js` and
  `admin.css`, built from `addons/booking/apps/admin/src/` (TypeScript and
  React).

The readable source of both ships inside the plugin, next to the build it
produces, together with the build configuration, so nothing has to be fetched
to inspect or rebuild it.

Everything else is already readable as shipped. `assets/js/*.js` and
`assets/css/*.css` are hand-written, with no build step and no minified
variant, and all of the PHP is plain source under `app/`. The other modules
under `addons/` are the same: plain PHP, JavaScript and CSS.

Both builds need Node 20 or newer and pnpm 10 (`npm install -g pnpm`).

To rebuild the main admin app, in the plugin folder:

1. `pnpm install`
2. `pnpm build`

That runs TypeScript against `apps/admin/tsconfig.json` and then Vite against
`apps/admin/vite.config.ts`, writing the bundle and its manifest back into
`assets/dist/`. The plugin reads `assets/dist/.vite/manifest.json` to find the
hashed filenames, so a rebuild needs no change in PHP. `pnpm type-check` and
`pnpm test` run the type checker and the unit tests on their own.

To rebuild the Booking admin screen, in the plugin folder:

1. `cd addons/booking`
2. `pnpm install`
3. `pnpm build`

That runs TypeScript against `addons/booking/apps/admin/tsconfig.json` and then
Vite against `addons/booking/apps/admin/vite.config.ts`, writing `admin.js` and
`admin.css` into `addons/booking/assets/dist/`.

The build tools are pinned in the `package.json` and `pnpm-lock.yaml` files
that ship with the plugin (one pair in the plugin folder, one in
`addons/booking/`): Vite 6, TypeScript 5, React 18, Tailwind CSS 4.

== External services ==

Your content, leads and settings stay on your site. The core plugin contacts one outside service, only in the admin, for the optional deactivation survey described first below. The other services are only contacted when you switch on the module that uses them and fill in its settings. Nothing is sent to them before that.

= Deactivation feedback (Flexa Product Intelligence) =

When you go to deactivate Flexa Local Services on the Plugins screen, a short optional survey asks why. It is served by Flexa's product intelligence service at https://product-intelligence.flexacommerce.com. It runs only on `wp-admin/plugins.php`, never on the front end, and never blocks deactivation: skip it, or let it fail, and the plugin still deactivates.

What is sent, and when:

* On opening the Plugins screen: a request to `/api/v1/config` (product slug and tier) to load the survey's settings. The answer is cached for 6 hours.
* When you deactivate or use the survey: the reason you pick and any message you choose to type, sent to `/api/v1/deactivations`, `/api/v1/events`, `/api/v1/feedback`, `/api/v1/feature-requests` or `/api/v1/recovery-events`.

Each request carries an anonymous identifier for the site (a random UUID), the plugin version and tier, and by default your WordPress version, PHP version and locale. No email address, site domain, user identity or raw IP address is collected. To stop sending the WordPress and PHP versions and locale, add `add_filter( 'fxlc_deactivation_survey_config', fn( $c ) => array( 'collect_environment' => false ) + $c );`. To switch the survey off entirely, add `add_filter( 'fxlc_deactivation_survey_enabled', '__return_false' );`.
Terms: https://flexacommerce.com/pages/terms
Privacy: https://flexacommerce.com/pages/privacy

= Anthropic (Claude API), AI Assistant module =

Used to write content, score leads, draft review replies and answer visitors in the site chat. When one of these runs, the prompt is sent to Anthropic: for the chat that is the visitor's question, the last few messages of the conversation and passages from your published content; for lead scoring, the lead's form answers. Requests go from your server with your own API key, only after you enter one.
Terms: https://www.anthropic.com/legal/commercial-terms
Privacy: https://www.anthropic.com/legal/privacy

= Stripe, Payments module =

Used to take card payments and recurring subscriptions (including Membership plans) through Stripe Checkout, and to receive Stripe's payment notifications. When a visitor pays, the amount, currency, item name and the payment's ID on your site are sent to Stripe, and the visitor enters their card details on Stripe's own page. For a subscription, the customer's email address is sent as well, so Stripe can send receipts and keep the subscription under one customer. When you act on a payment from the admin, the module also asks Stripe to issue a refund, create a discount coupon, cancel or resume a subscription, or retry a failed invoice; those requests carry the Stripe IDs involved and, for a refund or coupon, the amount. Only used after you enter your Stripe keys.
Terms: https://stripe.com/legal/ssa
Privacy: https://stripe.com/privacy

= Google Calendar, Booking module =

Optional two-way sync. Each booking is copied to your Google Calendar as an event with the service, the customer's name and contact details and the booking time, and busy times in that calendar are read back so they cannot be booked. Only used after you connect a Google account with your own OAuth client in the Booking settings.
Terms: https://policies.google.com/terms
Privacy: https://policies.google.com/privacy

= Cloudflare Turnstile, Booking module =

Optional bot check on the booking form. When switched on, the form loads Turnstile's script from Cloudflare, and on submit the check's token and the visitor's IP address are sent to Cloudflare to confirm the visitor is a person. Only used after you enter Turnstile keys.
Terms: https://www.cloudflare.com/website-terms/
Privacy: https://www.cloudflare.com/turnstile-privacy-policy/

= Your own webhook, Booking module =

If you enter a webhook URL in the Booking settings, booking events (the booking and the customer's details) are posted to that URL, which is a service you choose and control.

== Installation ==

1. Upload the plugin through Plugins > Add New, or copy the folder to `wp-content/plugins/`.
2. Activate it. The database tables for forms, submissions and leads are created on activation.
3. Open **Flexa Local** in the admin menu and work down the dashboard checklist.
4. Fill in Settings with your business name and phone, then add your first service.
5. Create a form under Forms, add the Form block to a page, and send yourself a test submission.
6. To take bookings, switch on Booking under **Flexa Local > Modules**, add services and hours, and put the Booking Form block on a page. The other modules are switched on the same way.

== Frequently Asked Questions ==

= Do I have to use all the modules? =

No. Every module is off until you switch it on under **Flexa Local > Modules**, and a module that is off loads no code. Most sites start with the core plugin and add Booking when they want appointments online.

= I already run the standalone Flexa Booking (or another Flexa add-on) plugin. What happens? =

The first time an administrator opens the admin after updating, the matching module is switched on and the old plugin is deactivated. The module uses the same tables and settings, so your bookings and customers stay where they are. A standalone plugin that is newer than the copy inside this plugin, or one that is active across a multisite network, is left alone, and the Modules screen says so.

= Can two customers book the same time? =

No. Each time is checked again when the booking is saved, so if two people pick the same slot at once, the second one is asked to choose another time.

= Do I need a specific theme? =

No. The blocks use your theme's colors and fonts where they can, and ship with enough styling of their own to look right in any block theme.

= Can I see what the plugin looks like with content in it? =

Yes. **Flexa Local > Tools** has a starter site for nine trades. Importing one creates example services, areas, testimonials, FAQs, team members, finished jobs, offers, a quote form and the ten or eleven pages that make up a service website, all editable like anything else you write. The same screen deletes them again, and only the items the import created.

= How does it know which page a lead came from? =

The form block writes the ID of the page it is rendered on into the submission. The Leads screen, the alert email and the CSV export all show that page, so one form reused across twenty service pages still tells you which service was being read.

= Who on my site can see the leads? =

Anyone who can edit other people's posts, which means editors and administrators. Authors and contributors can write and edit the service pages, areas and testimonials, but the Leads, Forms and Emails screens do not appear for them, and the REST routes behind those screens turn them away. If that is the wrong line for your site, the `fxlc_capabilities_can_manage_leads` filter moves it.

= Where do form submissions go? =

Into two custom database tables, readable in the Leads screen. They are not emailed anywhere unless you turn on notifications in Settings, and they are never sent to a third party service.

= Can I keep my existing contact form plugin? =

Yes. The content types and blocks work on their own, so skip the Forms and Leads screens. You lose the page attribution, which only works through the form in this plugin.

= Does the form work if a visitor has JavaScript disabled? =

Yes. The form is a real HTML form that posts to WordPress and redirects back to the page with a confirmation. JavaScript only upgrades it to submit in place.

= How do I stop spam without a CAPTCHA? =

Two checks run on every public submission: a hidden field that humans never fill in, and the time between the page rendering and the form arriving. Both are tunable with the `fxlc_form_spam_check` and `fxlc_form_spam_min_seconds` filters.

= What happens to my data if I delete the plugin? =

Settings are removed. The tables holding your leads and submissions are left alone, so deleting the plugin by accident does not destroy them. The same goes for the tables of bookings, customers, payments and the other modules. Drop those tables yourself if you want a clean slate.

= Is the admin area translatable? =

Yes, every string goes through the `flexa-local-services` text domain.

== Screenshots ==

1. Dashboard: leads waiting for a reply, today's bookings and the latest enquiries at a glance.
2. Leads: every form enquiry in one list, filtered by status, with the page it came from.
3. A lead's details, with one click to reply by email or call back.
4. Form builder: drag fields into place and map them to the lead's name, phone and email.
5. Email designer: build branded emails from blocks, preview them and send a test.
6. Bookings: online appointments with status, staff and filters by service and date.
7. A booking's details: change its status, reschedule it or download the calendar file.
8. Customers: a drag-and-drop pipeline from new to won or lost.
9. A customer's record: contact details, payments, tags, custom fields, tasks and activity.
10. Payments: revenue, paid and pending payments, refunds and PDF invoices.
11. Reviews: approve customer reviews with photos, see their tone and reply in public.
12. Analytics: events per day, form submissions, leads, bookings and conversion goals.
13. Lead sources: which campaigns and sites bring conversions, first or last touch.
14. Membership: plans, members, renewals and their status.
15. AI Assistant: a chat that answers visitors from your own pages, with the content it learns from.

== Changelog ==

= 1.1.4 =

* New: deactivating the plugin opens a short, optional survey asking why. It can be skipped and never blocks deactivation. What it sends, and how to switch it off, is listed under External services.
* New: a Settings link next to Deactivate on the Plugins screen.
* Fix: with no date picked, the Booking and Waitlist lists and the all-time Customers reports no longer come back empty or fail on MySQL in strict mode.

= 1.1.3 =

* Fix: the modules now load their translations from the plugin's own text domain, so one language pack covers the whole plugin.
* Fix: every module database query is prepared, table names included.
* Fix: the Modules screen loads its styles from a stylesheet instead of an inline style tag.
* Fix: the required-field mark on the booking and manage-booking forms is escaped.
* New: the lead form accepts at most 10 submissions per hour from one IP address. Change the limit with the fxlc_form_rate_limit filter, or set it to 0 to turn it off.
* Docs: the readme now covers the data sent to Stripe for subscriptions and how to build the Booking admin from source.

= 1.1.2 =

* New: the eight Flexa add-ons ship inside the plugin as modules: Booking, Customers (CRM), Payments, Reviews, Analytics, Membership, AI Assistant and Mobile API. All are off until you switch them on under Flexa Local > Modules.
* New: a site that ran one of the add-ons as its own plugin moves over to the module on its own, keeping its data.
* New: the module screens share the look of the main admin, and their pop-ups show above the full-screen admin.
* New: every content type gets a page of its own, and the starter sites have a fresh design.
* Fix: the Copy button now copies on admin pages served over plain HTTP.
* Fix: a phone extension is dialled after a pause instead of as part of the number.
* Booking: the date field now opens a styled calendar instead of the browser's bare date picker, on both the booking form and the reschedule form.
* Booking: fixed a double border that showed on an invalid field when it was focused.
* Booking: phone and email share one "at least one required" mark instead of each showing its own, since only one is actually needed.
* Booking: a field's error clears as soon as it's fixed, instead of waiting for the next submit attempt.

= 1.1.1 =

* An email text block whose tokens are all empty is left out of the sent email.
* Post type screens say "No FAQs found." and keep the label's case.

= 1.1.0 =

* First release.
* Seven content types: services, service areas, projects, testimonials, team, FAQs, coupons.
* Twelve blocks to display them.
* Form builder, Form block and `[flexa_local_form]` shortcode, Leads screen, CSV export.
* Starter sites for nine trades, from plumbing to pest control, imported and removed from the Tools screen.
* Leads record the page they were submitted from, shown in the admin, the alert email and the export.
* Email alert on every lead, addressed so that a reply reaches the customer.
* Honeypot and timing spam checks, no CAPTCHA.
* Leads, forms and email templates sit behind a higher capability than the content, so an author cannot read the customer details.
* REST API under `fxlc/v1`.

== Upgrade Notice ==

= 1.1.4 =
Adds an optional feedback survey when you deactivate the plugin.

= 1.1.3 =
Code review fixes: one text domain for all modules, prepared queries, and a rate limit on lead forms.

= 1.1.2 =
Adds online booking, CRM, payments, reviews, analytics, membership, AI and mobile app modules, all off until you switch them on.

= 1.1.1 =
Small email and label fixes.

= 1.1.0 =
First release.
