@livemapleads/piece-live-map-leads 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Live Map Leads
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# Live Map Leads — Activepieces piece
+
+Pull filtered local-business lists from map data inside your [Activepieces](https://www.activepieces.com)
+flows. Start a search and act on the results the moment they're ready.
+
+- **Action — Start a Search** — kick off a local-business search (`POST /api/v1/jobs`).
+- **Trigger — New Search Completed** — fires when one of your searches finishes, with its
+  record count, the credits charged, and ready-to-use download links (CSV, XLSX, JSON).
+- **Connection — API Key** — paste an API key from your Live Map Leads account settings.
+
+## How it talks to Live Map Leads
+
+The piece is a thin, typed client of the public [Live Map Leads API](https://livemapleads.com/api/v1/openapi.yaml)
+(`/api/v1`). It does **not** re-describe request or response shapes by hand:
+
+- `openapi.yaml` is vendored from the live, unauthenticated `GET /api/v1/openapi.yaml`.
+- `src/generated/v1.ts` holds the spec-derived **types** (build-time only — erased at runtime).
+- [`openapi-fetch`](https://openapi-ts.dev/openapi-fetch/) (~6 KB) is the single runtime
+  dependency; a wrong path, field, or query param fails to **compile**.
+
+## Trigger: polling now, instant later
+
+"New Search Completed" is a **polling** trigger: Activepieces checks the read-only list
+endpoint (`GET /api/v1/jobs?status=completed&since=…`) on its schedule and emits one item per
+newly-finished search. Dedupe is time-based on each search's completion time — exactly the
+`since` cursor the API exposes. Listing spends **no credits**.
+
+Polling-first is deliberate: the connector ships on the API alone, with no dependency on push
+delivery. An **instant** (webhook) variant is a drop-in upgrade when Live Map Leads adds
+push: only [`src/lib/triggers/new-search-completed.ts`](src/lib/triggers/new-search-completed.ts)
+changes its trigger strategy — the action, the API client, and the connection stay as they are.
+
+### Known limit
+
+Each poll fetches the newest 100 completed searches (the API maximum; the API has no forward
+pagination). If **more than 100** of your searches were to complete inside a single polling
+interval, the overflow beyond the newest 100 would not be emitted. This is the upstream API's
+accepted polling residual and is effectively unreachable in practice — an account runs one
+search at a time, so a poll interval can't accumulate 100+ completions. The instant (webhook)
+trigger removes the ceiling entirely.
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # tsc (sources + tests)
+npm run lint        # eslint
+npm run test        # vitest — runs against a MOCKED API, never spends credits
+npm run build       # emits dist/
+npm run check       # all of the above
+```
+
+To run it inside Activepieces locally, copy/symlink this package into your Activepieces
+`packages/pieces/community/live-map-leads` and use the standard piece hot-reload dev loop
+(`npm start` in the Activepieces repo). See the Activepieces
+[piece development docs](https://www.activepieces.com/docs/build-pieces/building-pieces/start-building).
+
+### Updating the client when the API changes
+
+The API contract is the OpenAPI spec. To pull in API changes:
+
+```bash
+# 1. Refresh the vendored spec from production (byte-identical to docs/api/openapi.yaml).
+curl -fsS https://livemapleads.com/api/v1/openapi.yaml -o openapi.yaml
+
+# 2. Regenerate the typed client (pinned generator → reproducible output).
+npm run gen:types   # openapi-typescript 7.13.0 → src/generated/v1.ts
+
+# 3. tsc will flag any action/trigger that no longer matches the new contract.
+npm run check
+```
+
+`--default-non-nullable false` (already in the `gen:types` script) makes request-body fields
+that carry a server-side default optional, so callers don't have to send them.
+
+## Publishing
+
+Two sanctioned routes (operator-gated — needs the npm scope / marketplace account):
+
+1. **Community / public npm (soft launch).** `npm publish --access public` under the
+   `@livemapleads` scope, then install it in Activepieces by package name. Fast; no SEO surface.
+2. **Contribute (cloud marketplace).** Open a PR adding this package to the Activepieces
+   monorepo under `packages/pieces/community/live-map-leads`. This earns the indexed
+   `activepieces.com/pieces/live-map-leads` listing page — the SEO-bearing path — and is done
+   once the piece is proven.
+
+Before publishing, confirm `minimumSupportedRelease` (in [`src/index.ts`](src/index.ts)) against
+your target Activepieces version, and that the `logoUrl` resolves.
+
+## License
+
+[MIT](../../LICENSE).

package/dist/generated/v1.d.ts

@@ -0,0 +1,320 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List completed searches
+         * @description List the calling account's completed searches, newest first, each with
+         *     its result count and download links. Only the calling account's own
+         *     searches are ever returned — no cross-account identifiers are exposed.
+         *     This is the polling source for a "New search completed" automation
+         *     trigger.
+         *
+         *     For incremental polling, pass `since` = the most recent `completedAt` you
+         *     have already seen; the response returns only searches that finished
+         *     strictly after it, ordered by `completedAt` descending. De-duplicate by
+         *     the stable `jobId`. See `hasMore` for the rare case where a single page
+         *     does not cover everything since `since`.
+         */
+        get: operations["listSearches"];
+        put?: never;
+        /**
+         * Start a search
+         * @description Start a new local-business search. Returns immediately with a `jobId`
+         *     and `status: "queued"`; the search runs in the background. Watch for it
+         *     to finish via `GET /jobs?status=completed&since=…`.
+         *
+         *     Provide a location as **exactly one** of `locationQuery` (text) or
+         *     `customGeolocation` (a drawn area) — one is required, and supplying both
+         *     is rejected.
+         */
+        post: operations["startSearch"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * @description Search definition. `additionalProperties: false` is a HARD part of the
+         *     contract: the v1 route MUST validate against this restricted field set and
+         *     reject any other field — it must NOT forward the raw body to the full
+         *     internal search schema. That internal schema also accepts add-on /
+         *     enrichment toggles (reviews, images, extra details — each billable),
+         *     premium / personal-data add-ons, and webhook routing (`deliverTo`); all of
+         *     those are DEFERRED from v1 (Phase 24.5) and MUST stay unreachable through
+         *     this endpoint (no billable add-on or personal-data path via v1). The field
+         *     names that DO appear here match the internal schema so the validated subset
+         *     maps onto the existing job-start path with no new credit logic. Exactly one
+         *     of `locationQuery` or `customGeolocation` is required.
+         */
+        StartSearchRequest: {
+            /**
+             * @description One or more search terms, e.g. "dentist" or "italian restaurant". Each term runs against the location.
+             * @example [
+             *       "dentist"
+             *     ]
+             */
+            searchStrings: string[];
+            /**
+             * @description Free-text location, e.g. "Austin, TX" or "Lyon, France". Mutually exclusive with `customGeolocation`.
+             * @example Austin, TX
+             */
+            locationQuery?: string;
+            customGeolocation?: components["schemas"]["GeoArea"];
+            /**
+             * @description Result language as a BCP-47 code.
+             * @default en
+             */
+            language?: string;
+            /** @description Optional cap on the number of places returned per search term. */
+            maxResults?: number;
+            /**
+             * @description How a business name must match your search term. `all` = no name filter; `contains` = name contains the term; `exact` = name equals the term.
+             * @default all
+             * @enum {string}
+             */
+            nameMatch?: "all" | "contains" | "exact";
+            /**
+             * @description Filter by website presence. `any` = no filter; `with` = only places that have a website; `without` = only places that do not.
+             * @default any
+             * @enum {string}
+             */
+            website?: "any" | "with" | "without";
+            /** @description Restrict results to these business categories, e.g. "dentist" or "art gallery". Values are lowercase and must each be a recognised category — an unknown value is rejected with 400. The recognised set is large (thousands of entries) and is versioned with the data provider, so it is not enumerated inline here; a future GET /api/v1/categories endpoint will expose the current list for connector dropdowns. Omit this field to apply no category filter. */
+            categories?: string[];
+            /**
+             * @description Exclude permanently or temporarily closed places.
+             * @default false
+             */
+            skipClosed?: boolean;
+            /** @description Optional per-search spending ceiling, in credits. The search stops before exceeding it. Recommended for unattended automations. */
+            capCredits?: number;
+        };
+        /** @description A drawn search area as GeoJSON. Coordinates are [longitude, latitude] pairs. Mutually exclusive with `locationQuery`. */
+        GeoArea: {
+            /** @enum {string} */
+            type: "Polygon" | "MultiPolygon";
+            /** @description GeoJSON coordinate array. For `Polygon`: an array of linear rings (each an array of [lng, lat] positions). For `MultiPolygon`: an array of polygons. */
+            coordinates: unknown[];
+        };
+        /**
+         * @example {
+         *       "jobId": "8f1d6c2a-3b4e-4f7a-9c1d-2e3f4a5b6c7d",
+         *       "status": "queued"
+         *     }
+         */
+        StartSearchResponse: {
+            /**
+             * Format: uuid
+             * @description Unique identifier for the search. Use it to match results later.
+             * @example 8f1d6c2a-3b4e-4f7a-9c1d-2e3f4a5b6c7d
+             */
+            jobId: string;
+            /**
+             * @description Always "queued" on a successful start.
+             * @enum {string}
+             */
+            status: "queued";
+        };
+        SearchList: {
+            /** @description Completed searches, newest first. */
+            data: components["schemas"]["SearchSummary"][];
+            /** @description True when more completed searches matched than fit in `limit` — the page was truncated to the newest `limit`. Rare for a single account. To retrieve the remainder, repeat the call with a larger `limit` (max 100) and the SAME `since`; only advance `since` to the newest `completedAt` you have seen once `hasMore` is false. Advancing `since` while `hasMore` is true would skip the older, un-returned searches. Results are de-duplicated by `jobId` regardless. */
+            hasMore: boolean;
+        };
+        /**
+         * @description A finished search. Mirrors the fields delivered to outbound webhooks (Phase 23), the existing "completed search" payload.
+         * @example {
+         *       "jobId": "8f1d6c2a-3b4e-4f7a-9c1d-2e3f4a5b6c7d",
+         *       "status": "completed",
+         *       "recordCount": 142,
+         *       "creditsCharged": 142,
+         *       "completedAt": "2026-06-12T14:22:05Z",
+         *       "downloads": {
+         *         "csv": "https://livemapleads.com/api/exports/download?token=eyJhbGciOi...",
+         *         "xlsx": "https://livemapleads.com/api/exports/download?token=eyJhbGciOi...",
+         *         "json": "https://livemapleads.com/api/exports/download?token=eyJhbGciOi..."
+         *       },
+         *       "summary": "Your search finished with 142 records."
+         *     }
+         */
+        SearchSummary: {
+            /**
+             * Format: uuid
+             * @description Stable identifier — use it as the de-duplication key when polling.
+             */
+            jobId: string;
+            /**
+             * @description Always `completed` for this endpoint (it lists completed searches); maps from the internal `complete` state. The full public lifecycle (`queued`/`running`/`completed`/`cancelled`/`failed`, mapping from the internal `queued`/`running`/`complete`/`aborted`/`failed`+`timed_out`) arrives with the single-search detail route in a later phase (24.5).
+             * @enum {string}
+             */
+            status: "completed";
+            /** @description Number of business records the search returned. */
+            recordCount: number;
+            /** @description Credits charged for this search (charge-on-success). */
+            creditsCharged: number;
+            /**
+             * Format: date-time
+             * @description When the search finished (RFC 3339).
+             */
+            completedAt: string;
+            /** @description Ready-to-use download links, one per format. Each is a signed, time-limited URL (about 7 days) that needs no API key. Null if download links are unavailable for this search. */
+            downloads: components["schemas"]["Downloads"] | null;
+            /**
+             * @description Short human-readable summary of the result.
+             * @example Your search finished with 142 records.
+             */
+            summary?: string;
+        };
+        /** @description Signed, time-limited download URLs by format. No API key needed to fetch. */
+        Downloads: {
+            /** Format: uri */
+            csv?: string;
+            /** Format: uri */
+            xlsx?: string;
+            /** Format: uri */
+            json?: string;
+        };
+        Error: {
+            /**
+             * @description Stable machine-readable error code.
+             * @example invalid_request
+             */
+            error: string;
+            /** @description Human-readable explanation. Do not parse — read `error`. */
+            message: string;
+        };
+    };
+    responses: {
+        /** @description The request body or query failed validation (e.g. unknown category, both location forms supplied, value out of range). */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "invalid_request",
+                 *       "message": "Provide exactly one of locationQuery or customGeolocation."
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Missing, invalid, or revoked API key. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "unauthorized",
+                 *       "message": "Missing or invalid API key."
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+        /** @description Rate limit exceeded for this key. */
+        TooManyRequests: {
+            headers: {
+                /** @description Seconds to wait before retrying. */
+                "Retry-After"?: number;
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "rate_limited",
+                 *       "message": "Too many requests. Retry after the indicated delay."
+                 *     }
+                 */
+                "application/json": components["schemas"]["Error"];
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    listSearches: {
+        parameters: {
+            query?: {
+                /**
+                 * @description Lifecycle filter. v1 supports only `completed` (the value a polling
+                 *     trigger needs); it is also the default.
+                 */
+                status?: "completed";
+                /**
+                 * @description Return only searches that completed strictly after this RFC 3339 timestamp. Omit on the first poll.
+                 * @example 2026-06-12T00:00:00Z
+                 */
+                since?: string;
+                /** @description Maximum number of searches to return. */
+                limit?: number;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description A page of completed searches, newest first. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SearchList"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    startSearch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["StartSearchRequest"];
+            };
+        };
+        responses: {
+            /** @description Search accepted and queued. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StartSearchResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+}

package/dist/generated/v1.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { liveMapLeadsAuth } from './lib/common/auth';
+export { liveMapLeadsAuth };
+export declare const liveMapLeads: import("@activepieces/pieces-framework").Piece<import("@activepieces/pieces-framework").SecretTextProperty<true>>;

package/dist/index.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveMapLeads = exports.liveMapLeadsAuth = void 0;
+// Live Map Leads — Activepieces piece.
+//
+// Pull filtered local-business lists from map data: start a search, then act on the results
+// when the search completes. A thin, typed client of the public Live Map Leads API
+// (https://livemapleads.com/api/v1) — the OpenAPI spec is the contract.
+const shared_1 = require("@activepieces/shared");
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const start_search_1 = require("./lib/actions/start-search");
+const auth_1 = require("./lib/common/auth");
+Object.defineProperty(exports, "liveMapLeadsAuth", { enumerable: true, get: function () { return auth_1.liveMapLeadsAuth; } });
+const new_search_completed_1 = require("./lib/triggers/new-search-completed");
+exports.liveMapLeads = (0, pieces_framework_1.createPiece)({
+    displayName: 'Live Map Leads',
+    description: 'Pull filtered local-business lists from map data. Start a search and get a notification when your results are ready to download.',
+    auth: auth_1.liveMapLeadsAuth,
+    // The lowest Activepieces release this piece is known to run on. Confirm/raise against
+    // your target Activepieces version before publishing (see README § Publishing).
+    minimumSupportedRelease: '0.36.1',
+    logoUrl: 'https://livemapleads.com/logo-icon.png',
+    categories: [shared_1.PieceCategory.MARKETING, shared_1.PieceCategory.SALES_AND_CRM],
+    authors: ['livemapleads'],
+    actions: [start_search_1.startSearchAction],
+    triggers: [new_search_completed_1.newSearchCompleted],
+});

package/dist/lib/actions/start-search.d.ts

@@ -0,0 +1,31 @@
+import { type StartSearchBody } from '../common/api';
+/** Shape of this action's prop values (kept permissive so the framework's inferred type assigns). */
+export interface StartSearchProps {
+    searchTerms: unknown;
+    location: string;
+    maxResults?: number;
+    nameMatch?: 'all' | 'contains' | 'exact';
+    website?: 'any' | 'with' | 'without';
+    categories?: unknown;
+    skipClosed?: boolean;
+    capCredits?: number;
+    language?: string;
+}
+/**
+ * Map the action's prop values to the API request body. Pure + exported so it is unit-
+ * tested without the Activepieces runtime. Optional fields are omitted entirely when unset
+ * so the API applies its own defaults. Throws when no search term survives trimming (the
+ * field is required, but an array of blanks would otherwise send an empty search).
+ */
+export declare function buildStartSearchBody(props: StartSearchProps): StartSearchBody;
+export declare const startSearchAction: import("@activepieces/pieces-framework").IAction<import("@activepieces/pieces-framework").SecretTextProperty<true>, {
+    searchTerms: import("@activepieces/pieces-framework").ArrayProperty<true>;
+    location: import("@activepieces/pieces-framework").ShortTextProperty<true>;
+    maxResults: import("@activepieces/pieces-framework").NumberProperty<false>;
+    nameMatch: import("@activepieces/pieces-framework").StaticDropdownProperty<"all" | "contains" | "exact", false> | import("@activepieces/pieces-framework").StaticDropdownProperty<"all" | "contains" | "exact", true>;
+    website: import("@activepieces/pieces-framework").StaticDropdownProperty<"any" | "with" | "without", false> | import("@activepieces/pieces-framework").StaticDropdownProperty<"any" | "with" | "without", true>;
+    categories: import("@activepieces/pieces-framework").ArrayProperty<false>;
+    skipClosed: import("@activepieces/pieces-framework").CheckboxProperty<false>;
+    capCredits: import("@activepieces/pieces-framework").NumberProperty<false>;
+    language: import("@activepieces/pieces-framework").ShortTextProperty<false>;
+}>;

package/dist/lib/actions/start-search.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startSearchAction = void 0;
+exports.buildStartSearchBody = buildStartSearchBody;
+// Action: "Start a Search" — POST /api/v1/jobs.
+//
+// Exposes the restricted public search fields (openapi.yaml StartSearchRequest). The
+// location is a plain text query (the natural input for a no-code user); the drawn-area
+// (GeoJSON) form the API also accepts is intentionally not surfaced here. Billable add-ons
+// and personal-data options are not part of the v1 surface at all, so they can't be
+// reached from this action.
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const api_1 = require("../common/api");
+const auth_1 = require("../common/auth");
+const client_1 = require("../common/client");
+/** Coerce an Activepieces array prop (its items are `unknown`) to clean, non-empty strings. */
+function toStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((item) => (typeof item === 'string' ? item.trim() : String(item ?? '').trim()))
+        .filter((item) => item.length > 0);
+}
+/**
+ * Map the action's prop values to the API request body. Pure + exported so it is unit-
+ * tested without the Activepieces runtime. Optional fields are omitted entirely when unset
+ * so the API applies its own defaults. Throws when no search term survives trimming (the
+ * field is required, but an array of blanks would otherwise send an empty search).
+ */
+function buildStartSearchBody(props) {
+    const searchStrings = toStringList(props.searchTerms);
+    if (searchStrings.length === 0) {
+        throw new Error('Enter at least one search term, e.g. "dentist".');
+    }
+    const location = (props.location ?? '').trim();
+    if (location.length === 0) {
+        throw new Error('Enter a location, e.g. "Austin, TX".');
+    }
+    const body = {
+        searchStrings,
+        locationQuery: location,
+    };
+    if (props.maxResults != null)
+        body.maxResults = props.maxResults;
+    if (props.nameMatch)
+        body.nameMatch = props.nameMatch;
+    if (props.website)
+        body.website = props.website;
+    if (props.skipClosed != null)
+        body.skipClosed = props.skipClosed;
+    if (props.capCredits != null)
+        body.capCredits = props.capCredits;
+    if (props.language && props.language.trim().length > 0)
+        body.language = props.language.trim();
+    const categories = toStringList(props.categories);
+    if (categories.length > 0)
+        body.categories = categories;
+    return body;
+}
+exports.startSearchAction = (0, pieces_framework_1.createAction)({
+    auth: auth_1.liveMapLeadsAuth,
+    name: 'start_search',
+    displayName: 'Start a Search',
+    description: 'Start a new local-business search. Returns right away with a search ID while the search runs in the background — use the "New Search Completed" trigger to pick up the results when they are ready.',
+    props: {
+        searchTerms: pieces_framework_1.Property.Array({
+            displayName: 'Search Terms',
+            description: 'What to look for, e.g. "dentist" or "italian restaurant". Add one term per line; each runs against your location.',
+            required: true,
+        }),
+        location: pieces_framework_1.Property.ShortText({
+            displayName: 'Location',
+            description: 'Where to search, e.g. "Austin, TX" or "Lyon, France".',
+            required: true,
+        }),
+        maxResults: pieces_framework_1.Property.Number({
+            displayName: 'Max Results per Term',
+            description: 'Optional cap on how many businesses to return for each search term. Leave empty for no cap.',
+            required: false,
+        }),
+        nameMatch: pieces_framework_1.Property.StaticDropdown({
+            displayName: 'Business Name Match',
+            description: 'How strictly a business name must match your search term.',
+            required: false,
+            options: {
+                options: [
+                    { label: 'Any name (no filter)', value: 'all' },
+                    { label: 'Name contains the term', value: 'contains' },
+                    { label: 'Name is exactly the term', value: 'exact' },
+                ],
+            },
+        }),
+        website: pieces_framework_1.Property.StaticDropdown({
+            displayName: 'Website Filter',
+            description: 'Keep only businesses with or without a website.',
+            required: false,
+            options: {
+                options: [
+                    { label: 'Any (no filter)', value: 'any' },
+                    { label: 'Only with a website', value: 'with' },
+                    { label: 'Only without a website', value: 'without' },
+                ],
+            },
+        }),
+        categories: pieces_framework_1.Property.Array({
+            displayName: 'Categories',
+            description: 'Optional. Restrict results to specific business categories (e.g. "dentist", "art gallery"). Each must be a recognised category — an unknown value is rejected. Leave empty to apply no category filter.',
+            required: false,
+        }),
+        skipClosed: pieces_framework_1.Property.Checkbox({
+            displayName: 'Skip Closed Businesses',
+            description: 'Exclude permanently or temporarily closed businesses.',
+            required: false,
+        }),
+        capCredits: pieces_framework_1.Property.Number({
+            displayName: 'Credit Limit',
+            description: 'Optional ceiling on how many credits this search may spend. Recommended for unattended automations.',
+            required: false,
+        }),
+        language: pieces_framework_1.Property.ShortText({
+            displayName: 'Result Language',
+            description: 'Optional language code for results (e.g. "en", "fr", "pt-br"). Defaults to English.',
+            required: false,
+        }),
+    },
+    async run(context) {
+        const body = buildStartSearchBody(context.propsValue);
+        return await (0, api_1.startSearch)((0, client_1.resolveApiKey)(context.auth), body);
+    },
+});

package/dist/lib/common/api.d.ts

@@ -0,0 +1,36 @@
+import type { components } from '../../generated/v1';
+/** The restricted public search request body (openapi.yaml StartSearchRequest). */
+export type StartSearchBody = components['schemas']['StartSearchRequest'];
+/** 202 response from starting a search. */
+export type StartSearchResult = components['schemas']['StartSearchResponse'];
+/** One completed search in the polling list. */
+export type SearchSummary = components['schemas']['SearchSummary'];
+/** A page of completed searches. */
+export type SearchList = components['schemas']['SearchList'];
+/**
+ * A failed Live Map Leads API call. `status` is the HTTP status (0 if the request never
+ * reached the server); `code` is the stable machine code from the API (`unauthorized`,
+ * `rate_limited`, `invalid_request`, …) or a synthetic one for transport failures.
+ * `message` is already ICP-friendly — safe to surface to the user.
+ */
+export declare class LiveMapLeadsApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/**
+ * Start a search (POST /jobs). Returns the `{ jobId, status: "queued" }` accept response.
+ * The search runs in the background; credits are charged only on success, and never for a
+ * search that fails. Throws `LiveMapLeadsApiError` on any non-2xx / transport failure.
+ */
+export declare function startSearch(apiKey: string, body: StartSearchBody, baseUrl?: string): Promise<StartSearchResult>;
+/**
+ * List the account's completed searches, newest first (GET /jobs). `since` (RFC 3339)
+ * returns only searches that finished strictly after it — pass the newest `completedAt`
+ * you have already seen for incremental polling. Read-only: spends no credits. Throws
+ * `LiveMapLeadsApiError` on any non-2xx / transport failure.
+ */
+export declare function listCompletedSearches(apiKey: string, params: {
+    since?: string;
+    limit?: number;
+}, baseUrl?: string): Promise<SearchList>;

package/dist/lib/common/api.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiveMapLeadsApiError = void 0;
+exports.startSearch = startSearch;
+exports.listCompletedSearches = listCompletedSearches;
+const client_1 = require("./client");
+const constants_1 = require("./constants");
+/**
+ * A failed Live Map Leads API call. `status` is the HTTP status (0 if the request never
+ * reached the server); `code` is the stable machine code from the API (`unauthorized`,
+ * `rate_limited`, `invalid_request`, …) or a synthetic one for transport failures.
+ * `message` is already ICP-friendly — safe to surface to the user.
+ */
+class LiveMapLeadsApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'LiveMapLeadsApiError';
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.LiveMapLeadsApiError = LiveMapLeadsApiError;
+/** Narrow an unknown error body to the API's `{ error, message }` Error schema. */
+function readErrorBody(body) {
+    if (body && typeof body === 'object') {
+        const record = body;
+        return {
+            code: typeof record.error === 'string' ? record.error : undefined,
+            message: typeof record.message === 'string' ? record.message : undefined,
+        };
+    }
+    return {};
+}
+/**
+ * Turn an `openapi-fetch` failure into a `LiveMapLeadsApiError` with copy a non-technical
+ * user can act on. Known statuses get tailored guidance; the API's own human `message` is
+ * preferred for validation (400) errors, which are already specific and readable.
+ */
+function toApiError(errorBody, response) {
+    const status = response?.status ?? 0;
+    const { code: bodyCode, message: bodyMessage } = readErrorBody(errorBody);
+    if (status === 401 || status === 403) {
+        return new LiveMapLeadsApiError(status, bodyCode ?? 'unauthorized', 'Your API key was not accepted. Open your Live Map Leads account settings, check the key is correct and still active, then reconnect.');
+    }
+    if (status === 429) {
+        const retryAfter = response?.headers.get('retry-after');
+        const wait = retryAfter ? ` Wait ${retryAfter} seconds and try again.` : ' Please slow down and try again shortly.';
+        return new LiveMapLeadsApiError(status, bodyCode ?? 'rate_limited', `Too many requests.${wait}`);
+    }
+    if (status === 400 && bodyMessage) {
+        // The API's 400 message is human-readable and specific (e.g. an unrecognised category).
+        return new LiveMapLeadsApiError(status, bodyCode ?? 'invalid_request', bodyMessage);
+    }
+    if (status === 0) {
+        return new LiveMapLeadsApiError(0, 'network_error', "Couldn't reach Live Map Leads. Check your connection and try again.");
+    }
+    return new LiveMapLeadsApiError(status, bodyCode ?? 'request_failed', bodyMessage ?? 'Something went wrong talking to Live Map Leads. Please try again in a moment.');
+}
+/**
+ * Start a search (POST /jobs). Returns the `{ jobId, status: "queued" }` accept response.
+ * The search runs in the background; credits are charged only on success, and never for a
+ * search that fails. Throws `LiveMapLeadsApiError` on any non-2xx / transport failure.
+ */
+async function startSearch(apiKey, body, baseUrl = constants_1.PROD_BASE_URL) {
+    let result;
+    try {
+        result = await (0, client_1.makeClient)(apiKey, baseUrl).POST('/jobs', { body });
+    }
+    catch {
+        // fetch rejected (DNS / connection / abort) — openapi-fetch surfaces HTTP errors via
+        // `error`, but transport failures throw, so convert them to the friendly network error.
+        throw toApiError(undefined, undefined);
+    }
+    if (result.data === undefined) {
+        throw toApiError(result.error, result.response);
+    }
+    return result.data;
+}
+/**
+ * List the account's completed searches, newest first (GET /jobs). `since` (RFC 3339)
+ * returns only searches that finished strictly after it — pass the newest `completedAt`
+ * you have already seen for incremental polling. Read-only: spends no credits. Throws
+ * `LiveMapLeadsApiError` on any non-2xx / transport failure.
+ */
+async function listCompletedSearches(apiKey, params, baseUrl = constants_1.PROD_BASE_URL) {
+    let result;
+    try {
+        result = await (0, client_1.makeClient)(apiKey, baseUrl).GET('/jobs', {
+            params: {
+                query: {
+                    status: 'completed',
+                    limit: params.limit ?? constants_1.MAX_LIST_LIMIT,
+                    ...(params.since ? { since: params.since } : {}),
+                },
+            },
+        });
+    }
+    catch {
+        throw toApiError(undefined, undefined);
+    }
+    if (result.data === undefined) {
+        throw toApiError(result.error, result.response);
+    }
+    return result.data;
+}

package/dist/lib/common/auth.d.ts

@@ -0,0 +1 @@
+export declare const liveMapLeadsAuth: import("@activepieces/pieces-framework").SecretTextProperty<true>;

package/dist/lib/common/auth.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.liveMapLeadsAuth = void 0;
+// The connection users set up once: their Live Map Leads API key.
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const api_1 = require("./api");
+const client_1 = require("./client");
+const AUTH_DESCRIPTION = `Connect your Live Map Leads account with an API key.
+
+1. Sign in at https://livemapleads.com and open **Account settings → API keys**.
+2. Create a key and copy it — it is shown only once.
+3. Paste it below.
+
+The key acts on behalf of your account: it can start searches (which spend credits) and read your results. Keep it secret.`;
+exports.liveMapLeadsAuth = pieces_framework_1.PieceAuth.SecretText({
+    displayName: 'API Key',
+    description: AUTH_DESCRIPTION,
+    required: true,
+    // Confirm the key works the moment it is entered, using the read-only "list searches"
+    // endpoint (spends no credits). Only an explicit key rejection blocks the connection; a
+    // transient outage is not treated as a bad key.
+    validate: async ({ auth }) => {
+        try {
+            await (0, api_1.listCompletedSearches)((0, client_1.resolveApiKey)(auth), { limit: 1 });
+            return { valid: true };
+        }
+        catch (error) {
+            if (error instanceof api_1.LiveMapLeadsApiError && (error.status === 401 || error.status === 403)) {
+                return { valid: false, error: 'That API key was not accepted. Check it is correct and still active in your account settings.' };
+            }
+            // Network/server hiccup — don't reject a possibly-good key over a transient error.
+            return { valid: true };
+        }
+    },
+});

package/dist/lib/common/client.d.ts

@@ -0,0 +1,17 @@
+import { type Client } from 'openapi-fetch';
+import type { paths } from '../../generated/v1';
+export type V1Client = Client<paths>;
+/**
+ * Resolve the API key string from an Activepieces auth value. A `SecretText` connection is
+ * typed as `{ type, secret_text }` by the SDK but has historically been delivered to piece
+ * code as the bare string — this accepts BOTH shapes so the key resolves correctly across
+ * Activepieces versions. Throws if neither form yields a non-empty key.
+ */
+export declare function resolveApiKey(auth: unknown): string;
+/**
+ * Build an authenticated client. `apiKey` is the account API key from Live Map Leads
+ * account settings; it is sent on the `x-api-key` header of every request. `baseUrl` is
+ * overridable only so tests can point at a mock server — published actions/triggers always
+ * use the production base.
+ */
+export declare function makeClient(apiKey: string, baseUrl?: string): V1Client;

package/dist/lib/common/client.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveApiKey = resolveApiKey;
+exports.makeClient = makeClient;
+// The typed HTTP client for the Live Map Leads API.
+//
+// The client is generated from the OpenAPI spec (`openapi.yaml`, vendored from the live
+// `GET /api/v1/openapi.yaml`): `src/generated/v1.ts` holds the spec-derived TYPES
+// (build-time only, erased at runtime) and `openapi-fetch` is the single ~6 KB runtime
+// dependency. A wrong path, field, or query param fails to COMPILE — the spec is the
+// contract, nothing here re-describes request or response shapes by hand. To refresh after
+// the API changes: `npm run gen:types` (see README § Updating the client).
+const openapi_fetch_1 = __importDefault(require("openapi-fetch"));
+const constants_1 = require("./constants");
+/**
+ * Resolve the API key string from an Activepieces auth value. A `SecretText` connection is
+ * typed as `{ type, secret_text }` by the SDK but has historically been delivered to piece
+ * code as the bare string — this accepts BOTH shapes so the key resolves correctly across
+ * Activepieces versions. Throws if neither form yields a non-empty key.
+ */
+function resolveApiKey(auth) {
+    if (typeof auth === 'string') {
+        const key = auth.trim();
+        if (key.length > 0)
+            return key;
+    }
+    if (auth && typeof auth === 'object' && 'secret_text' in auth) {
+        const raw = auth.secret_text;
+        if (typeof raw === 'string') {
+            const key = raw.trim();
+            if (key.length > 0)
+                return key;
+        }
+    }
+    throw new Error('Missing Live Map Leads API key. Reconnect your account in the connection settings.');
+}
+/**
+ * Build an authenticated client. `apiKey` is the account API key from Live Map Leads
+ * account settings; it is sent on the `x-api-key` header of every request. `baseUrl` is
+ * overridable only so tests can point at a mock server — published actions/triggers always
+ * use the production base.
+ */
+function makeClient(apiKey, baseUrl = constants_1.PROD_BASE_URL) {
+    return (0, openapi_fetch_1.default)({
+        baseUrl,
+        headers: { 'x-api-key': apiKey },
+    });
+}

package/dist/lib/common/constants.d.ts

@@ -0,0 +1,9 @@
+/** The public Live Map Leads API base. Every action and trigger talks to this. */
+export declare const PROD_BASE_URL = "https://livemapleads.com/api/v1";
+/**
+ * Page size for listing completed searches. The API caps `limit` at 100; we ask for the
+ * max so the "New Search Completed" trigger picks up everything finished since the last
+ * check in a single call (one account rarely finishes more than 100 searches between
+ * checks).
+ */
+export declare const MAX_LIST_LIMIT = 100;

package/dist/lib/common/constants.js

@@ -0,0 +1,13 @@
+"use strict";
+// Shared constants for the Live Map Leads piece.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LIST_LIMIT = exports.PROD_BASE_URL = void 0;
+/** The public Live Map Leads API base. Every action and trigger talks to this. */
+exports.PROD_BASE_URL = 'https://livemapleads.com/api/v1';
+/**
+ * Page size for listing completed searches. The API caps `limit` at 100; we ask for the
+ * max so the "New Search Completed" trigger picks up everything finished since the last
+ * check in a single call (one account rarely finishes more than 100 searches between
+ * checks).
+ */
+exports.MAX_LIST_LIMIT = 100;

package/dist/lib/triggers/new-search-completed.d.ts

@@ -0,0 +1,19 @@
+import { type Polling } from '@activepieces/pieces-common';
+import { type AppConnectionValueForAuthProperty, TriggerStrategy } from '@activepieces/pieces-framework';
+import { liveMapLeadsAuth } from '../common/auth';
+type AuthValue = AppConnectionValueForAuthProperty<typeof liveMapLeadsAuth>;
+/**
+ * Fetch completed searches and map them to the helper's poll-item shape (exported for unit
+ * tests). `lastFetchEpochMS` is supplied by the helper: `0` on the manual "test trigger"
+ * run (return the most recent searches), or the timestamp of the newest search seen so far
+ * on a live poll. We translate it into the API's `since` filter so the server only returns
+ * newer searches; each item carries its `completedAt` as `epochMilliSeconds` for dedupe.
+ */
+export declare function pollCompletedSearches(auth: AuthValue, lastFetchEpochMS: number): Promise<{
+    epochMilliSeconds: number;
+    data: unknown;
+}[]>;
+/** The polling definition wired into the trigger hooks (exported for integration tests). */
+export declare const polling: Polling<AuthValue, Record<string, never>>;
+export declare const newSearchCompleted: import("@activepieces/pieces-framework").ITrigger<TriggerStrategy.WEBHOOK, import("@activepieces/pieces-framework").SecretTextProperty<true>, {}> | import("@activepieces/pieces-framework").ITrigger<TriggerStrategy.POLLING, import("@activepieces/pieces-framework").SecretTextProperty<true>, {}> | import("@activepieces/pieces-framework").ITrigger<TriggerStrategy.MANUAL, import("@activepieces/pieces-framework").SecretTextProperty<true>, {}> | import("@activepieces/pieces-framework").ITrigger<TriggerStrategy.APP_WEBHOOK, import("@activepieces/pieces-framework").SecretTextProperty<true>, {}>;
+export {};

package/dist/lib/triggers/new-search-completed.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newSearchCompleted = exports.polling = void 0;
+exports.pollCompletedSearches = pollCompletedSearches;
+// Trigger: "New Search Completed" — fires once per search as it finishes.
+//
+// Polling-first (decoupled from any push/webhook delivery): Activepieces checks the
+// read-only list endpoint (GET /api/v1/jobs?status=completed&since=…) on its schedule and
+// emits one item per newly-completed search. Dedupe is TIME-BASED on `completedAt`: the
+// helper stores the newest timestamp it has seen and only emits searches that finished
+// strictly after it — which is exactly the `since` cursor the API exposes. Listing spends
+// no credits.
+//
+// An instant (webhook) variant is a future, drop-in upgrade: only this file's strategy
+// changes — the action and the API client stay as-is (see README § Polling vs. instant).
+const pieces_common_1 = require("@activepieces/pieces-common");
+const pieces_framework_1 = require("@activepieces/pieces-framework");
+const api_1 = require("../common/api");
+const auth_1 = require("../common/auth");
+const client_1 = require("../common/client");
+const constants_1 = require("../common/constants");
+/**
+ * Fetch completed searches and map them to the helper's poll-item shape (exported for unit
+ * tests). `lastFetchEpochMS` is supplied by the helper: `0` on the manual "test trigger"
+ * run (return the most recent searches), or the timestamp of the newest search seen so far
+ * on a live poll. We translate it into the API's `since` filter so the server only returns
+ * newer searches; each item carries its `completedAt` as `epochMilliSeconds` for dedupe.
+ */
+async function pollCompletedSearches(auth, lastFetchEpochMS) {
+    const since = lastFetchEpochMS > 0 ? new Date(lastFetchEpochMS).toISOString() : undefined;
+    const page = await (0, api_1.listCompletedSearches)((0, client_1.resolveApiKey)(auth), { since, limit: constants_1.MAX_LIST_LIMIT });
+    // One page (the newest MAX_LIST_LIMIT, the API maximum) per poll. The API exposes no
+    // forward pagination — only `since` + `limit` (≤100) + `hasMore` — so if MORE than 100
+    // searches completed since the last poll, the page is truncated to the newest 100 and the
+    // older overflow is not emitted (the time cursor advances past them). This is the upstream
+    // API's documented, accepted polling residual ("rare for a single account") and is bounded
+    // to near-impossible here: an account runs one search at a time (each takes seconds to
+    // minutes), so >100 completing inside one poll interval cannot realistically occur. The
+    // instant (webhook) trigger upgrade removes the ceiling entirely. See README § Known limits.
+    return page.data.map((search) => ({
+        epochMilliSeconds: Date.parse(search.completedAt),
+        data: search,
+    }));
+}
+/** The polling definition wired into the trigger hooks (exported for integration tests). */
+exports.polling = {
+    strategy: pieces_common_1.DedupeStrategy.TIMEBASED,
+    items: ({ auth, lastFetchEpochMS }) => pollCompletedSearches(auth, lastFetchEpochMS),
+};
+exports.newSearchCompleted = (0, pieces_framework_1.createTrigger)({
+    auth: auth_1.liveMapLeadsAuth,
+    name: 'new_search_completed',
+    displayName: 'New Search Completed',
+    description: 'Fires when one of your searches finishes, with its record count, the credits charged, and ready-to-use download links (CSV, XLSX, JSON).',
+    type: pieces_framework_1.TriggerStrategy.POLLING,
+    props: {},
+    sampleData: {
+        jobId: '8f1d6c2a-3b4e-4f7a-9c1d-2e3f4a5b6c7d',
+        status: 'completed',
+        recordCount: 142,
+        creditsCharged: 142,
+        completedAt: '2026-06-12T14:22:05Z',
+        downloads: {
+            csv: 'https://livemapleads.com/api/exports/download?token=eyJhbGciOi...',
+            xlsx: 'https://livemapleads.com/api/exports/download?token=eyJhbGciOi...',
+            json: 'https://livemapleads.com/api/exports/download?token=eyJhbGciOi...',
+        },
+        summary: 'Your search finished with 142 records.',
+    },
+    async onEnable(context) {
+        await pieces_common_1.pollingHelper.onEnable(exports.polling, {
+            store: context.store,
+            auth: context.auth,
+            propsValue: context.propsValue,
+        });
+    },
+    async onDisable(context) {
+        await pieces_common_1.pollingHelper.onDisable(exports.polling, {
+            store: context.store,
+            auth: context.auth,
+            propsValue: context.propsValue,
+        });
+    },
+    async run(context) {
+        return await pieces_common_1.pollingHelper.poll(exports.polling, {
+            store: context.store,
+            auth: context.auth,
+            propsValue: context.propsValue,
+            files: context.files,
+        });
+    },
+    async test(context) {
+        return await pieces_common_1.pollingHelper.test(exports.polling, {
+            store: context.store,
+            auth: context.auth,
+            propsValue: context.propsValue,
+            files: context.files,
+        });
+    },
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@livemapleads/piece-live-map-leads",
+  "version": "0.1.0",
+  "description": "Activepieces piece for Live Map Leads — start local-business searches and trigger when a search completes.",
+  "keywords": [
+    "activepieces",
+    "activepieces-piece",
+    "live-map-leads",
+    "leads",
+    "local-business",
+    "automation"
+  ],
+  "homepage": "https://livemapleads.com",
+  "bugs": {
+    "url": "https://github.com/LiveMapLeads/connectors/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LiveMapLeads/connectors.git",
+    "directory": "activepieces"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "gen:types": "openapi-typescript openapi.yaml --default-non-nullable false -o src/generated/v1.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+  "dependencies": {
+    "@activepieces/pieces-common": "0.12.4",
+    "@activepieces/pieces-framework": "0.30.0",
+    "openapi-fetch": "0.17.0"
+  },
+  "devDependencies": {
+    "@activepieces/shared": "^0.92.0",
+    "@types/node": "^22.10.2",
+    "eslint": "^9.17.0",
+    "openapi-typescript": "7.13.0",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.18.1",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}