@xapp/stentor-service-fieldroutes 0.0.1

package/LICENSE.md

@@ -0,0 +1,176 @@
+                               Apache License
+                         Version 2.0, January 2004
+                      http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+        Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+        stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+        that You distribute, all copyright, patent, trademark, and
+        attribution notices from the Source form of the Work,
+        excluding those notices that do not pertain to any part of
+        the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+        distribution, then any Derivative Works that You distribute must
+        include a readable copy of the attribution notices contained
+        within such NOTICE file, excluding those notices that do not
+        pertain to any part of the Derivative Works, in at least one
+        of the following places: within a NOTICE text file distributed
+        as part of the Derivative Works; within the Source form or
+        documentation, if provided along with the Derivative Works; or,
+        within a display generated by the Derivative Works, if and
+        wherever such third-party notices normally appear. The contents
+        of the NOTICE file are for informational purposes only and
+        do not modify the License. You may add Your own attribution
+        notices within Derivative Works that You distribute, alongside
+        or as an addendum to the NOTICE text from the Work, provided
+        that such additional attribution notices cannot be construed
+        as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,45 @@
+## @xapp/stentor-service-fieldroutes
+
+Implementation of `CrmService` for [FieldRoutes](https://api.fieldroutes.com/index) (formerly PestRoutes) — a field-service management platform for pest control and lawn care.
+
+### Status
+
+Scaffold. The `CrmService` surface (`send`, `getAvailability`) is implemented, but the FieldRoutes
+API details (endpoint paths, request encoding, response envelope) are modeled from the documented
+conventions and **must be verified against the live API and a real office** before production use.
+Everything HTTP flows through the single `request()` method in `FieldRoutesService`, so confirming
+the transport is a localized change. Search the source for `TODO` and `NOTE:`.
+
+### Configuration
+
+`FieldRoutesService` is constructed with:
+
+- `subdomain` — the office subdomain, e.g. `acmepest` → `https://acmepest.fieldroutes.com/api`
+- `authenticate()` — returns `{ authenticationKey, authenticationToken }` (office-scoped credentials)
+- `appId` — the Studio app id
+- `sourceID` (optional) — FieldRoutes lead source id to stamp on created customers
+- `defaultAppointmentType` (optional) — appointment type id used when one can't be resolved
+
+### Behavior
+
+`send()`:
+
+1. Matches an existing customer by phone/email (`customer/search`).
+2. Updates the match or creates a new customer (`customer/update` / `customer/create`).
+3. If the lead carries a `DATETIME`, books an appointment (`appointment/create`) — non-fatal on failure.
+
+### To verify against the FieldRoutes docs
+
+- Auth: are `authenticationKey`/`authenticationToken` query params, form fields, or headers?
+- Search: does `customer/search` return `customerIDs`, and is it GET or POST?
+- Create/update: response envelope + the id field name (`customerID`?).
+- Appointment/subscription: the required fields for booking, and appointment-type ids.
+- Availability: whether `getAvailability` should be backed by route capacity / `appointment/search`.
+
+### Testing
+
+```bash
+yarn workspace @xapp/stentor-service-fieldroutes local
+```
+
+Tests mock the HTTP layer with `axios-mock-adapter`; no live credentials required.

package/lib/FieldRoutesService.d.ts

@@ -0,0 +1,82 @@
+/*! Copyright (c) 2025, XAPP AI */
+import { FetchService } from "stentor-service-fetch";
+import { BaseService, CrmResponse, CrmService, CrmServiceAvailability, CrmServiceAvailabilityOptions, CrmServiceAvailabilitySettings, DateTimeRange, ExternalLead } from "stentor-models";
+import { CustomerQuery, FieldRoutesAppointment, FieldRoutesCustomer, FieldRoutesResponse } from "./models";
+/**
+ * Returns the FieldRoutes credentials for a request.
+ *
+ * FieldRoutes (formerly PestRoutes) authenticates every call with an office-scoped
+ * `authenticationKey` + `authenticationToken` pair.
+ *
+ * @see https://api.fieldroutes.com/index
+ */
+export interface FieldRoutesAuthenticator {
+    (): Promise<{
+        authenticationKey: string;
+        authenticationToken: string;
+    }>;
+}
+export interface FieldRoutesServiceProps extends BaseService, CrmServiceAvailabilitySettings {
+    appId: string;
+    /**
+     * The office subdomain, e.g. "acmepest" -> https://acmepest.fieldroutes.com/api
+     */
+    subdomain: string;
+    channel?: string;
+    authenticate: FieldRoutesAuthenticator;
+    openAI?: {
+        apiKey: string;
+    };
+    /**
+     * FieldRoutes appointment type id used when we cannot resolve one from the description.
+     */
+    defaultAppointmentType?: string;
+    /**
+     * FieldRoutes lead source id (numeric string) to stamp on created customers.
+     */
+    sourceID?: string;
+}
+/**
+ * CrmService implementation for FieldRoutes.
+ *
+ * NOTE: The FieldRoutes API surface (endpoint paths, request encoding, response envelope) is
+ * modeled here from the documented PestRoutes/FieldRoutes conventions and MUST be verified against
+ * the live docs at https://api.fieldroutes.com/index and a real office before going to production.
+ * The HTTP transport is centralized in {@link FieldRoutesService.request} to keep that easy to adjust.
+ */
+export declare class FieldRoutesService extends FetchService implements CrmService {
+    private props;
+    constructor(props: FieldRoutesServiceProps);
+    private get baseUrl();
+    /**
+     * getAvailability is not yet wired to FieldRoutes; returns full availability so the scheduler
+     * does not block. TODO: back this with appointment/search + route capacity.
+     */
+    getAvailability(range: DateTimeRange, _options?: CrmServiceAvailabilityOptions): Promise<CrmServiceAvailability>;
+    /**
+     * Send a lead to FieldRoutes: match-or-create the customer, then (if a date was provided)
+     * create the appointment.
+     */
+    send(externalLead: ExternalLead, extras?: Record<string, unknown>): Promise<CrmResponse>;
+    /**
+     * Search for customers by phone or email. Returns the matching FieldRoutes customer ids.
+     */
+    getCustomers(query: CustomerQuery): Promise<FieldRoutesResponse<string[]>>;
+    /**
+     * Create a customer in FieldRoutes. Returns the new customer id in `data`.
+     */
+    addCustomer(customer: FieldRoutesCustomer): Promise<FieldRoutesResponse<string>>;
+    /**
+     * Update an existing customer. `customer.customerID` must be set.
+     */
+    updateCustomer(customer: FieldRoutesCustomer): Promise<FieldRoutesResponse<string>>;
+    /**
+     * Create an appointment in FieldRoutes.
+     */
+    addAppointment(appointment: FieldRoutesAppointment): Promise<FieldRoutesResponse<string>>;
+    /**
+     * Single HTTP chokepoint. Normalizes transport + FieldRoutes' `success`/`errorMessage` envelope
+     * into a {@link FieldRoutesResponse}. Adjust here if the live API differs from the assumed shape.
+     */
+    private request;
+}

package/lib/FieldRoutesService.js

@@ -0,0 +1,280 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldRoutesService = void 0;
+/*! Copyright (c) 2025, XAPP AI */
+const stentor_service_fetch_1 = require("stentor-service-fetch");
+const stentor_logger_1 = require("stentor-logger");
+const axios_1 = __importDefault(require("axios"));
+const addresser_1 = require("addresser");
+const util_1 = require("./util");
+const CRM_DEBUG = process.env.CRM_DEBUG === "true";
+/**
+ * CrmService implementation for FieldRoutes.
+ *
+ * NOTE: The FieldRoutes API surface (endpoint paths, request encoding, response envelope) is
+ * modeled here from the documented PestRoutes/FieldRoutes conventions and MUST be verified against
+ * the live docs at https://api.fieldroutes.com/index and a real office before going to production.
+ * The HTTP transport is centralized in {@link FieldRoutesService.request} to keep that easy to adjust.
+ */
+class FieldRoutesService extends stentor_service_fetch_1.FetchService {
+    constructor(props) {
+        super(props);
+        this.props = Object.assign({}, props);
+        if (!this.props.channel) {
+            this.props.channel = "Chat";
+        }
+    }
+    get baseUrl() {
+        return `https://${this.props.subdomain}.fieldroutes.com/api`;
+    }
+    /**
+     * getAvailability is not yet wired to FieldRoutes; returns full availability so the scheduler
+     * does not block. TODO: back this with appointment/search + route capacity.
+     */
+    getAvailability(range, _options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            (0, stentor_logger_1.log)().debug(`${this.constructor.name} getAvailability not implemented, returning full availability.`);
+            return { range, unavailabilities: [] };
+        });
+    }
+    /**
+     * Send a lead to FieldRoutes: match-or-create the customer, then (if a date was provided)
+     * create the appointment.
+     */
+    send(externalLead, extras) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const crmResponse = {
+                status: "Failure",
+                message: ""
+            };
+            try {
+                const transcript = (0, util_1.leadToTranscript)(externalLead, this.props.appId);
+                const names = (0, util_1.getName)(externalLead);
+                const field = (name) => { var _a; return (_a = externalLead.fields.find((x) => x.name === name)) === null || _a === void 0 ? void 0 : _a.value; };
+                const address = field("ADDRESS");
+                const phone = field("PHONE");
+                const email = field("EMAIL");
+                const message = field("MESSAGE");
+                const dateTime = field("DATETIME");
+                let parsedAddress;
+                if (address) {
+                    try {
+                        parsedAddress = (0, addresser_1.parseAddress)(address);
+                    }
+                    catch (err) {
+                        // Non-fatal: we still capture the lead, just without a structured address.
+                        (0, stentor_logger_1.log)().warn(`FieldRoutes: Invalid address "${address}": ${err}`);
+                    }
+                }
+                const notesParts = [message, transcript].filter(Boolean);
+                const crmRequest = {
+                    fname: names.firstName,
+                    lname: names.lastName,
+                    phone1: phone,
+                    email,
+                    // FieldRoutes caps the customer notes field at 7500 chars.
+                    notes: notesParts.join("\n\n").substring(0, 7500),
+                    sourceID: this.props.sourceID,
+                    officeID: extras === null || extras === void 0 ? void 0 : extras.officeID
+                };
+                if (parsedAddress) {
+                    crmRequest.address = parsedAddress.addressLine1;
+                    crmRequest.city = parsedAddress.placeName;
+                    crmRequest.state = parsedAddress.stateAbbreviation;
+                    crmRequest.zip = parsedAddress.zipCode;
+                }
+                // Match an existing customer by phone or email.
+                const query = {};
+                if (phone) {
+                    query.phone = phone;
+                }
+                if (email) {
+                    query.email = email;
+                }
+                const matches = yield this.getCustomers(query);
+                if (matches.status === "Failure") {
+                    crmResponse.message = matches.error || "Failed to search customers";
+                    return crmResponse;
+                }
+                const existingId = (_a = matches.data) === null || _a === void 0 ? void 0 : _a[0];
+                let customerId;
+                if (existingId) {
+                    crmRequest.customerID = existingId;
+                    const updated = yield this.updateCustomer(crmRequest);
+                    if (updated.status === "Failure") {
+                        crmResponse.message = updated.error || "Failed to update customer";
+                        return crmResponse;
+                    }
+                    customerId = existingId;
+                }
+                else {
+                    const created = yield this.addCustomer(crmRequest);
+                    if (created.status === "Failure") {
+                        crmResponse.message = created.error || "Failed to create customer";
+                        return crmResponse;
+                    }
+                    customerId = created.data;
+                }
+                // Only book an appointment when we have both a customer and a requested date.
+                if (customerId && dateTime) {
+                    const appt = {
+                        customerID: customerId,
+                        type: this.props.defaultAppointmentType,
+                        date: dateTime.substring(0, 10),
+                        notes: message
+                    };
+                    const booked = yield this.addAppointment(appt);
+                    if (booked.status === "Failure") {
+                        // Non-fatal: the lead/customer is already captured.
+                        (0, stentor_logger_1.log)().warn(`FieldRoutes: customer saved but appointment failed: ${booked.error}`);
+                    }
+                }
+                crmResponse.status = "Success";
+                crmResponse.refId = customerId;
+            }
+            catch (err) {
+                (0, stentor_logger_1.log)().error(`FieldRoutes error send(): ${err}`);
+                crmResponse.message = `${err}`;
+            }
+            return crmResponse;
+        });
+    }
+    /**
+     * Search for customers by phone or email. Returns the matching FieldRoutes customer ids.
+     */
+    getCustomers(query) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const auth = yield this.props.authenticate();
+            const params = {
+                authenticationKey: auth.authenticationKey,
+                authenticationToken: auth.authenticationToken
+            };
+            if (query.email) {
+                params.email = query.email;
+            }
+            else if (query.phone) {
+                params.phone = query.phone;
+            }
+            const config = {
+                method: "get",
+                url: `${this.baseUrl}/customer/search`,
+                params
+            };
+            const response = yield this.request(config, "customer/search");
+            if (response.status === "Failure") {
+                return response;
+            }
+            const ids = (((_a = response.data) === null || _a === void 0 ? void 0 : _a.customerIDs) || []).map((id) => `${id}`);
+            return { status: "Success", data: ids };
+        });
+    }
+    /**
+     * Create a customer in FieldRoutes. Returns the new customer id in `data`.
+     */
+    addCustomer(customer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const auth = yield this.props.authenticate();
+            const data = Object.assign({ authenticationKey: auth.authenticationKey, authenticationToken: auth.authenticationToken }, customer);
+            const config = {
+                method: "post",
+                url: `${this.baseUrl}/customer/create`,
+                headers: { Accept: "application/json", "Content-Type": "application/json" },
+                data: JSON.stringify(data)
+            };
+            const response = yield this.request(config, "customer/create");
+            if (response.status === "Failure") {
+                return response;
+            }
+            return { status: "Success", data: ((_a = response.data) === null || _a === void 0 ? void 0 : _a.customerID) ? `${response.data.customerID}` : undefined };
+        });
+    }
+    /**
+     * Update an existing customer. `customer.customerID` must be set.
+     */
+    updateCustomer(customer) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const auth = yield this.props.authenticate();
+            const data = Object.assign({ authenticationKey: auth.authenticationKey, authenticationToken: auth.authenticationToken }, customer);
+            const config = {
+                method: "post",
+                url: `${this.baseUrl}/customer/update`,
+                headers: { Accept: "application/json", "Content-Type": "application/json" },
+                data: JSON.stringify(data)
+            };
+            const response = yield this.request(config, "customer/update");
+            if (response.status === "Failure") {
+                return response;
+            }
+            return { status: "Success", data: `${customer.customerID}` };
+        });
+    }
+    /**
+     * Create an appointment in FieldRoutes.
+     */
+    addAppointment(appointment) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const auth = yield this.props.authenticate();
+            const data = Object.assign({ authenticationKey: auth.authenticationKey, authenticationToken: auth.authenticationToken }, appointment);
+            const config = {
+                method: "post",
+                url: `${this.baseUrl}/appointment/create`,
+                headers: { Accept: "application/json", "Content-Type": "application/json" },
+                data: JSON.stringify(data)
+            };
+            const response = yield this.request(config, "appointment/create");
+            if (response.status === "Failure") {
+                return response;
+            }
+            return { status: "Success", data: ((_a = response.data) === null || _a === void 0 ? void 0 : _a.appointmentID) ? `${response.data.appointmentID}` : undefined };
+        });
+    }
+    /**
+     * Single HTTP chokepoint. Normalizes transport + FieldRoutes' `success`/`errorMessage` envelope
+     * into a {@link FieldRoutesResponse}. Adjust here if the live API differs from the assumed shape.
+     */
+    request(config, apiCall) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = { status: "Failure" };
+            try {
+                if (CRM_DEBUG) {
+                    (0, stentor_logger_1.log)().info(`[CRM_DEBUG] FieldRoutes ${apiCall} REQUEST: ${JSON.stringify((0, util_1.redactConfig)(config))}`);
+                }
+                const response = yield (0, axios_1.default)(config);
+                if (CRM_DEBUG) {
+                    (0, stentor_logger_1.log)().info(`[CRM_DEBUG] FieldRoutes ${apiCall} RESPONSE: ${JSON.stringify(response.data)}`);
+                }
+                const body = response.data;
+                if (body && body.success === false) {
+                    result.error = `[${apiCall}] ${body.errorMessage || (body.errors || []).join("; ") || "FieldRoutes API error"}`;
+                    (0, stentor_logger_1.log)().error(`FieldRoutes API Error ${result.error}`);
+                    return result;
+                }
+                result.status = "Success";
+                result.data = response.data;
+            }
+            catch (err) {
+                result.error = `[${apiCall}] ${err instanceof Error ? err.message : err}`;
+                (0, stentor_logger_1.log)().error(`FieldRoutes: request failed ${result.error}`);
+            }
+            return result;
+        });
+    }
+}
+exports.FieldRoutesService = FieldRoutesService;
+//# sourceMappingURL=FieldRoutesService.js.map

package/lib/FieldRoutesService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FieldRoutesService.js","sourceRoot":"","sources":["../src/FieldRoutesService.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+/*! Copyright (c) 2025, XAPP AI */
+export * from "./FieldRoutesService";
+export * from "./models";

package/lib/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/*! Copyright (c) 2025, XAPP AI */
+__exportStar(require("./FieldRoutesService"), exports);
+__exportStar(require("./models"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kCAAkC;AAClC,uDAAqC;AACrC,2CAAyB"}

package/lib/models.d.ts

@@ -0,0 +1,100 @@
+/*! Copyright (c) 2025, XAPP AI */
+export interface FieldRoutesExternalLeadExtras {
+    /**
+     * Typically aligned with the session ID to allow the same customer to have multiple conversations and create multiple leads.
+     */
+    externalId?: string;
+    /**
+     * The URL of the website the lead is on when the lead capture is complete
+     */
+    source?: string;
+    /**
+     * ID of the bot.  Pass this in if you aren't using 'bot' or the STUDIO_APP_ID
+     */
+    botId?: string;
+    /**
+     * Was the session abandoned i.e. widget was closed (= no more data)?
+     */
+    isAbandoned?: boolean;
+}
+/**
+ * A customer in FieldRoutes.
+ *
+ * Field names follow FieldRoutes' snake_case convention. Verify against the live schema at
+ * https://<subdomain>.fieldroutes.com/api/customer before extending.
+ *
+ * @see https://api.fieldroutes.com/index (Customer entity)
+ */
+export interface FieldRoutesCustomer {
+    /**
+     * FieldRoutes customer id. Present on existing customers, absent when creating.
+     */
+    customerID?: string;
+    fname?: string;
+    lname?: string;
+    companyName?: string;
+    /** Street address line 1 */
+    address?: string;
+    city?: string;
+    state?: string;
+    zip?: string;
+    /** Primary phone. FieldRoutes also exposes phone1/phone2 — map as needed. */
+    phone1?: string;
+    email?: string;
+    /** Free text notes; used to carry the transcript / message. */
+    notes?: string;
+    /** FieldRoutes lead source id (numeric string). Configured per office. */
+    sourceID?: string;
+    /**
+     * Office (subdomain) the customer belongs to. Only relevant for multi-office keys.
+     */
+    officeID?: string;
+}
+/**
+ * An appointment in FieldRoutes.
+ *
+ * @see https://api.fieldroutes.com/index (Appointment entity)
+ */
+export interface FieldRoutesAppointment {
+    appointmentID?: string;
+    customerID: string;
+    /** FieldRoutes appointment type id (numeric string). Maps from the job description. */
+    type?: string;
+    /** yyyy-MM-dd of the requested service date. */
+    date?: string;
+    /** HH:mm start of the arrival window. */
+    start?: string;
+    /** HH:mm end of the arrival window. */
+    end?: string;
+    /** Subscription this appointment belongs to, when booking recurring service. */
+    subscriptionID?: string;
+    notes?: string;
+}
+/**
+ * Internal, normalized result wrapper mirroring the pattern used by the other CRM services
+ * (ServiceMinder, FieldPulse). `data` holds whatever the caller needs from the FieldRoutes response.
+ */
+export interface FieldRoutesResponse<Data = any> {
+    status: "Success" | "Failure";
+    error?: string;
+    data?: Data;
+}
+/**
+ * The raw envelope FieldRoutes returns on every call.
+ *
+ * TODO: confirm exact field names against the live API. FieldRoutes (formerly PestRoutes) returns
+ * `success`, an errors array, and an entity-specific id list (e.g. `customerIDs`) on searches.
+ */
+export interface FieldRoutesApiEnvelope {
+    success?: boolean;
+    errorMessage?: string;
+    errors?: string[];
+    /** Search endpoints return an id list, e.g. customerIDs / appointmentIDs. */
+    [key: string]: unknown;
+}
+export interface CustomerQuery {
+    ids?: string[];
+    name?: string;
+    phone?: string;
+    email?: string;
+}

package/lib/models.js

@@ -0,0 +1,4 @@
+"use strict";
+/*! Copyright (c) 2025, XAPP AI */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=models.js.map

package/lib/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":";AAAA,kCAAkC"}

package/lib/util.d.ts

@@ -0,0 +1,24 @@
+/*! Copyright (c) 2025, XAPP AI */
+import { AxiosRequestConfig } from "axios";
+import { ExternalLead } from "stentor-models";
+/**
+ * Returns a shallow copy of an Axios config with FieldRoutes credentials masked, for safe logging.
+ *
+ * Credentials ride in BOTH `params` (search) and the JSON-stringified `data` body (create/update),
+ * so both are scrubbed. Anything unparseable is dropped rather than logged raw.
+ */
+export declare function redactConfig(config: AxiosRequestConfig): Record<string, unknown>;
+export interface ParsedName {
+    firstName: string;
+    lastName: string;
+}
+/**
+ * Pull a first/last name out of a lead.
+ *
+ * Prefers an explicit FIRST_NAME/LAST_NAME pair, otherwise splits a FULL_NAME on the last space.
+ */
+export declare function getName(lead: ExternalLead): ParsedName;
+/**
+ * Flatten a lead transcript into a single string, prefixing each turn with user/bot.
+ */
+export declare function leadToTranscript(lead: ExternalLead, appId?: string): string;

package/lib/util.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactConfig = redactConfig;
+exports.getName = getName;
+exports.leadToTranscript = leadToTranscript;
+const SECRET_KEYS = ["authenticationKey", "authenticationToken"];
+/**
+ * Returns a shallow copy of an Axios config with FieldRoutes credentials masked, for safe logging.
+ *
+ * Credentials ride in BOTH `params` (search) and the JSON-stringified `data` body (create/update),
+ * so both are scrubbed. Anything unparseable is dropped rather than logged raw.
+ */
+function redactConfig(config) {
+    const redact = (obj) => {
+        const copy = Object.assign({}, obj);
+        for (const key of SECRET_KEYS) {
+            if (key in copy) {
+                copy[key] = "***";
+            }
+        }
+        return copy;
+    };
+    const out = { method: config.method, url: config.url };
+    if (config.params) {
+        out.params = redact(config.params);
+    }
+    if (typeof config.data === "string") {
+        try {
+            out.data = redact(JSON.parse(config.data));
+        }
+        catch (_a) {
+            out.data = "***unserializable***";
+        }
+    }
+    else if (config.data && typeof config.data === "object") {
+        out.data = redact(config.data);
+    }
+    return out;
+}
+/**
+ * Pull a first/last name out of a lead.
+ *
+ * Prefers an explicit FIRST_NAME/LAST_NAME pair, otherwise splits a FULL_NAME on the last space.
+ */
+function getName(lead) {
+    var _a, _b, _c;
+    const fields = lead.fields || [];
+    const firstNameField = fields.find((field) => field.name === "FIRST_NAME");
+    const lastNameField = fields.find((field) => field.name === "LAST_NAME");
+    if (firstNameField || lastNameField) {
+        return {
+            firstName: (_a = firstNameField === null || firstNameField === void 0 ? void 0 : firstNameField.value) !== null && _a !== void 0 ? _a : "",
+            lastName: (_b = lastNameField === null || lastNameField === void 0 ? void 0 : lastNameField.value) !== null && _b !== void 0 ? _b : ""
+        };
+    }
+    const fullNameField = fields.find((field) => field.name === "FULL_NAME");
+    if (fullNameField && fullNameField.value.trim()) {
+        const parts = fullNameField.value.trim().split(/\s+/);
+        const lastName = parts.length > 1 ? ((_c = parts.pop()) !== null && _c !== void 0 ? _c : "") : "";
+        return {
+            firstName: parts.join(" "),
+            lastName
+        };
+    }
+    return { firstName: "", lastName: "" };
+}
+/**
+ * Flatten a lead transcript into a single string, prefixing each turn with user/bot.
+ */
+function leadToTranscript(lead, appId) {
+    const botId = appId || process.env["STUDIO_APP_ID"];
+    let transcript = "";
+    (lead.transcript || []).forEach((x) => {
+        var _a;
+        const fromId = (_a = x.from) === null || _a === void 0 ? void 0 : _a.id;
+        const isBot = fromId === botId || fromId === "bot";
+        const prefix = isBot ? `${botId || "bot"}: ` : "user: ";
+        transcript += `${prefix}${x.message} \n`;
+    });
+    return transcript;
+}
+//# sourceMappingURL=util.js.map

package/lib/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "@xapp/stentor-service-fieldroutes",
+    "license": "Apache-2.0",
+    "publishConfig": {
+        "access": "public"
+    },
+    "version": "0.0.1",
+    "description": "Service to integrate with FieldRoutes",
+    "types": "lib/index",
+    "main": "lib/index",
+    "files": [
+        "lib"
+    ],
+    "engines": {
+        "node": "^20 || ^22 || ^24"
+    },
+    "devDependencies": {
+        "@types/chai": "5.2.3",
+        "@types/sinon": "4.3.3",
+        "@xapp/config": "0.3.0",
+        "axios-mock-adapter": "2.1.0",
+        "chai": "4.5.0",
+        "dotenv": "17.4.2",
+        "mocha": "11.7.5",
+        "sinon": "21.0.0",
+        "stentor-logger": "1.74.0",
+        "stentor-models": "1.74.0",
+        "stentor-service-fetch": "1.74.0",
+        "ts-node": "10.9.2",
+        "typescript": "5.9.3"
+    },
+    "peerDependencies": {
+        "stentor-logger": "1.x",
+        "stentor-models": "1.x",
+        "stentor-service-fetch": "1.x"
+    },
+    "scripts": {
+        "prepack": "yarn build",
+        "build": "tsc -d true -p .",
+        "clean": "rm -rf ./lib/*",
+        "test": "mocha --recursive --timeout 12000 -r ts-node/register \"./src/**/*.test.ts\"",
+        "local": "mocha --recursive --timeout 12000 -r ts-node/register \"./src/**/*.ftest.ts\""
+    },
+    "dependencies": {
+        "addresser": "1.1.20",
+        "axios": "1.18.1",
+        "date-fns": "4.1.0"
+    }
+}