@fleegital/web 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+This package runs on carriers' own websites, so a breaking change here breaks
+someone else's site. Versions follow semver strictly, and anything that changes
+what an existing call does gets a major.
+
+## Unreleased
+
+### Added
+- `@fleegital/web/form`: `ApplicationForm` for a form that works out of the box,
+  and `useApplicationForm` for your own markup. Deduplicates applicants across
+  the whole company, records consent against the exact wording shown, carries an
+  anonymous first-visit id, and catches bots with a honeypot field.
+
+- `@fleegital/web/analytics`: `createAnalytics` for website analytics —
+  automatic page views including SPA route changes, batching, a send when the
+  tab is hidden, device class, and the arriving campaign carried across the
+  whole visit. No cookie, no third-party script, nothing a person typed.
+- `ApplicationForm` and `useApplicationForm` take an optional `analytics`, and
+  report `form_view`, `form_start` and `form_submit` into it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fleegital
+
+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

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @fleegital/web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The driver application form for carriers running Fleegital, as a package your
+developers install instead of a script tag.
+
+```bash
+npm install @fleegital/web
+```
+
+Your publishable key is in Fleegital under **Settings → Data management →
+Recruiting configuration → Website applications**, together with the list of
+websites allowed to submit. A key that is not used from an allowed origin is
+refused, so the key being public is not a way in.
+
+## The form
+
+```tsx
+import { ApplicationForm } from "@fleegital/web/form";
+
+<ApplicationForm
+  publishableKey="pk_live_…"
+  onSuccess={(message) => router.push("/thanks")}
+  onError={(message) => toast(message)}
+  className="my-form"
+/>
+```
+
+The package ships no stylesheet. The markup is plain elements with your
+`className` on the form, so your own CSS owns it.
+
+### Your own markup
+
+```tsx
+import { useApplicationForm } from "@fleegital/web/form";
+
+const f = useApplicationForm({ publishableKey: "pk_live_…" });
+
+if (f.state === "loading") return <Spinner />;
+if (f.state === "sent") return <p>{f.message}</p>;
+
+<form onSubmit={async (e) => {
+  e.preventDefault();
+  const res = await f.submit();
+  if (!res.ok) showError(res.error);
+}}>
+  <input value={f.values.first_name} onChange={(e) => f.setValue("first_name", e.target.value)} />
+  {f.errors.first_name?.[0] && <small>{f.errors.first_name[0]}</small>}
+
+  <label>
+    <input type="checkbox" checked={f.consentGranted}
+           onChange={(e) => f.setConsentGranted(e.target.checked)} />
+    {f.config?.consentText}
+  </label>
+
+  {/* A field no person sees. Leave it in: it is how bots are caught. */}
+  <input {...f.honeypotProps} tabIndex={-1} aria-hidden style={{ position: "absolute", left: -10000 }} />
+</form>
+```
+
+`f.config` carries the company name, the consent wording and version, the brand
+colour and the logo — all from your Fleegital settings, so changing them there
+changes the form without a deploy.
+
+## Website analytics
+
+```bash
+npm install @fleegital/web
+```
+
+```ts
+import { createAnalytics } from "@fleegital/web/analytics";
+
+const analytics = createAnalytics({ publishableKey: "pk_live_…" });
+```
+
+That is the whole setup. It records a page view on load and on every SPA route
+change, batches events, and sends what is queued when the tab is hidden.
+
+| | |
+|---|---|
+| `analytics.pageView(path?)` | Record a page view yourself (use with `autoPageViews: false`). |
+| `analytics.track(event, path?)` | `page_view`, `form_view`, `form_start`, `form_submit`. |
+| `analytics.flush()` | Send what is queued now. |
+| `analytics.stop()` | Stop listening, unwrap `history`, send what is left. |
+
+Options: `autoPageViews` (default `true`) and `flushInterval` in milliseconds
+(default `3000`), plus `publishableKey` and `origin`.
+
+### The application funnel
+
+Hand the analytics object to the form and the three funnel steps are recorded
+for you — the form became usable, the applicant typed something, the
+application was accepted:
+
+```tsx
+<ApplicationForm publishableKey="pk_live_…" analytics={analytics} />
+```
+
+Or with your own markup:
+
+```ts
+const f = useApplicationForm({ publishableKey: "pk_live_…", analytics });
+```
+
+Without it the page view is still recorded, but the funnel columns in Fleegital
+stay empty — and a page view is not an attempt.
+
+### What it collects
+
+An anonymous id for the browser, an id for the visit, the path, the referring
+host when it is somebody else's, a device class of `mobile`, `tablet` or
+`desktop`, and the `utm_*` tags the visit arrived on.
+
+It sets **no cookie**, loads **no third-party script**, sends nothing to anyone
+but your own Fleegital endpoint, and collects nothing a person typed. The ids
+live in `localStorage` and `sessionStorage` and never leave the browser except
+in these events. Where storage is blocked, nothing is recorded and nothing
+breaks.
+
+The campaign is remembered for the whole visit, not read fresh on each page: a
+visitor who arrives from an ad and reads three pages counts as three pages for
+that campaign.
+
+### It will not break your site
+
+No call throws, no failure is retried, and nothing is logged to the console. A
+page view is not worth an error on a carrier's careers page. On a browser
+without `fetch` `keepalive` (Firefox before 133) a last unsent batch can be lost
+when the tab closes; everything before it is already gone.
+
+## What it does that a plain `fetch` would not
+
+- **Deduplicates across your whole company.** A driver who already applied, in
+  any phone format, updates their record instead of becoming a second lead.
+- **Records consent** against the exact wording and version shown, which is what
+  the text-message gate reads before anything is sent.
+- **Carries a first-visit id** so the lead can be traced to the visit it came
+  from. Anonymous, `localStorage` only, no cookie, nothing to a third party, and
+  silently skipped where storage is blocked.
+- **Catches bots** with the honeypot field, without a CAPTCHA.
+
+## Outcomes
+
+`submit()` resolves to `{ ok: true, message }` or
+`{ ok: false, error, fields?, stale }`.
+
+`stale` means your consent wording changed in Fleegital while the page was open:
+reload it. `fields` carries per-field messages, keyed by field name.
+
+Accepted applications, ones held for review and ones that tripped the spam trap
+all get the same answer, deliberately — a submitter cannot learn which happened.
+What a recruiter needs is in Fleegital.
+
+## Privacy
+
+The package sets no cookie, loads no third-party script, and sends nothing
+anywhere but your Fleegital intake endpoint on `www.fleegital.app`. The only
+thing it stores is the anonymous visit id above.
+
+## Versions
+
+This runs on your website, so a change here can break your site. Versions
+follow semver strictly: anything that changes what an existing call does gets a
+major. Pin the major and read [CHANGELOG.md](CHANGELOG.md) before moving it.
+
+Published builds carry [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+so you can verify the tarball you installed was built from a commit in this
+repository.
+
+## Support
+
+Bugs and documentation problems: [open an issue](https://github.com/fleegital/fleegital-web/issues).
+Anything about your own company's keys, leads or settings belongs in the app,
+not in a public issue. Security reports: see [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/analytics/analytics.d.ts

@@ -0,0 +1,28 @@
+import { type AnalyticsEventName, type FleegitalOptions } from "../shared/client.js";
+export interface AnalyticsOptions extends FleegitalOptions {
+    /**
+     * Record a page view on load and on every SPA route change. Default true.
+     * Turn it off to call `pageView()` yourself from your router.
+     */
+    autoPageViews?: boolean;
+    /** How long events wait to be batched, in milliseconds. Default 3000. */
+    flushInterval?: number;
+}
+export interface Analytics {
+    /** Records a page view. Defaults to the current path. */
+    pageView: (path?: string) => void;
+    /** Records one of the funnel events. */
+    track: (event: AnalyticsEventName, path?: string) => void;
+    /** Sends whatever is queued now, rather than waiting for the timer. */
+    flush: () => void;
+    /** Stops listening and sends what is left. */
+    stop: () => void;
+}
+/**
+ * Starts collecting. Returns a no-op on the server, so importing this in a
+ * framework that renders on the server costs nothing and breaks nothing.
+ *
+ * Nothing here throws into the host page. A carrier's careers site must not
+ * go down because a page view could not be counted.
+ */
+export declare function createAnalytics(options: AnalyticsOptions): Analytics;

package/dist/analytics/analytics.js

@@ -0,0 +1,162 @@
+import { sendEvents, MAX_BATCH, } from "../shared/client.js";
+import { visitorId } from "../shared/visitor.js";
+import { sessionId, visitUtm } from "../shared/session.js";
+import { device } from "../shared/device.js";
+/**
+ * The queue is bounded. A tab left open for a day with no network should cost
+ * a fixed amount of memory, not a growing one. Past the cap the oldest events
+ * go, because what someone is doing now is worth more than what they did an
+ * hour ago on a page that never reported.
+ */
+const MAX_QUEUED = 200;
+const noop = {
+    pageView: () => { },
+    track: () => { },
+    flush: () => { },
+    stop: () => { },
+};
+function currentPath() {
+    try {
+        return window.location.pathname + window.location.search;
+    }
+    catch {
+        return "/";
+    }
+}
+/** The referring host, but only when it is somebody else's. */
+function referrerHost() {
+    try {
+        if (!document.referrer)
+            return undefined;
+        const u = new URL(document.referrer);
+        if (u.host === window.location.host)
+            return undefined;
+        return u.host;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Starts collecting. Returns a no-op on the server, so importing this in a
+ * framework that renders on the server costs nothing and breaks nothing.
+ *
+ * Nothing here throws into the host page. A carrier's careers site must not
+ * go down because a page view could not be counted.
+ */
+export function createAnalytics(options) {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return noop;
+    const { publishableKey, origin } = options;
+    const interval = Math.max(500, options.flushInterval ?? 3000);
+    const auto = options.autoPageViews ?? true;
+    let queue = [];
+    let timer;
+    let stopped = false;
+    const send = (keepalive) => {
+        if (queue.length === 0)
+            return;
+        const batch = queue.slice(0, MAX_BATCH);
+        queue = queue.slice(MAX_BATCH);
+        // Deliberately not awaited: the caller is a click or a navigation.
+        void sendEvents({ publishableKey, origin }, batch, keepalive);
+    };
+    const schedule = () => {
+        if (timer !== undefined || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            send(false);
+        }, interval);
+    };
+    const push = (event, path) => {
+        if (stopped)
+            return;
+        const vid = visitorId();
+        // No id, no event: the server requires one, and an event that cannot be
+        // tied to a visit cannot be counted as a visitor either.
+        if (!vid)
+            return;
+        const utm = visitUtm();
+        queue.push({
+            event_name: event,
+            path: (path ?? currentPath()).slice(0, 400),
+            visitor_id: vid,
+            session_id: sessionId(),
+            referrer_host: referrerHost(),
+            device: device(),
+            utm: Object.keys(utm).length > 0 ? utm : undefined,
+            occurred_at: new Date().toISOString(),
+        });
+        if (queue.length > MAX_QUEUED)
+            queue = queue.slice(queue.length - MAX_QUEUED);
+        schedule();
+    };
+    // A tab being hidden is the last reliable moment to send. pagehide is the
+    // backstop for browsers that go straight there, and both can fire, which is
+    // harmless: the queue is emptied as it is read.
+    const onHide = () => {
+        if (document.visibilityState === "hidden")
+            send(true);
+    };
+    const onPageHide = () => send(true);
+    document.addEventListener("visibilitychange", onHide);
+    window.addEventListener("pagehide", onPageHide);
+    // SPA navigation. pushState and replaceState fire no event of their own, so
+    // they are wrapped; popstate covers the back button. Both are put back as
+    // they were on stop(), so an app that mounts and unmounts does not stack
+    // wrappers.
+    const origPush = window.history.pushState;
+    const origReplace = window.history.replaceState;
+    const onPop = () => push("page_view");
+    if (auto) {
+        const wrap = (fn) => function (...args) {
+            const r = fn.apply(this, args);
+            // After the URL has changed, not before.
+            push("page_view");
+            return r;
+        };
+        try {
+            window.history.pushState = wrap(origPush);
+            window.history.replaceState = wrap(origReplace);
+            window.addEventListener("popstate", onPop);
+        }
+        catch {
+            /* a page that froze history keeps manual pageView() */
+        }
+        push("page_view");
+    }
+    return {
+        pageView: (path) => push("page_view", path),
+        track: (event, path) => push(event, path),
+        flush: () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            send(false);
+        },
+        stop: () => {
+            if (stopped)
+                return;
+            stopped = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            document.removeEventListener("visibilitychange", onHide);
+            window.removeEventListener("pagehide", onPageHide);
+            if (auto) {
+                try {
+                    window.history.pushState = origPush;
+                    window.history.replaceState = origReplace;
+                    window.removeEventListener("popstate", onPop);
+                }
+                catch {
+                    /* nothing to put back */
+                }
+            }
+            send(true);
+        },
+    };
+}

package/dist/analytics/index.d.ts

@@ -0,0 +1,6 @@
+export { createAnalytics } from "./analytics.js";
+export type { Analytics, AnalyticsOptions } from "./analytics.js";
+export type { AnalyticsEventName } from "../shared/client.js";
+export { ANALYTICS_EVENTS } from "../shared/client.js";
+export { visitorId } from "../shared/visitor.js";
+export { sessionId } from "../shared/session.js";

package/dist/analytics/index.js

@@ -0,0 +1,4 @@
+export { createAnalytics } from "./analytics.js";
+export { ANALYTICS_EVENTS } from "../shared/client.js";
+export { visitorId } from "../shared/visitor.js";
+export { sessionId } from "../shared/session.js";

package/dist/form/ApplicationForm.d.ts

@@ -0,0 +1,16 @@
+import type { ApplicationValues, EventSink, FleegitalOptions } from "../shared/client.js";
+/** Fields a carrier can ask for, in the order they are shown. */
+export type FieldName = keyof ApplicationValues;
+export interface ApplicationFormProps extends FleegitalOptions {
+    /** Pass what `createAnalytics()` returned to record the funnel steps. */
+    analytics?: EventSink;
+    fields?: FieldName[];
+    labels?: Partial<Record<FieldName, string>>;
+    /** Called once the server has accepted the submission. */
+    onSuccess?: (message: string) => void;
+    onError?: (message: string) => void;
+    /** Put your own class on the <form>; the package ships no stylesheet. */
+    className?: string;
+    submitLabel?: string;
+}
+export declare function ApplicationForm(props: ApplicationFormProps): import("react").JSX.Element;

package/dist/form/ApplicationForm.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useApplicationForm } from "./useApplicationForm.js";
+const DEFAULT_FIELDS = ["first_name", "last_name", "phone", "email", "cdl_class", "experience_years"];
+const DEFAULT_LABELS = {
+    first_name: "First name",
+    last_name: "Last name",
+    phone: "Mobile phone",
+    email: "Email",
+    cdl_class: "CDL class",
+    experience_years: "Years driving",
+    position: "Position",
+    location: "Location",
+    notes: "Anything else",
+};
+const REQUIRED = ["first_name", "phone"];
+/*
+ * A plain, unstyled form. It carries no CSS of its own beyond what is needed to
+ * hide the spam trap, because a carrier's site has its own design and a package
+ * that arrives with opinions about colour is a package they fight. Anyone who
+ * wants a different layout uses `useApplicationForm` and writes their own.
+ */
+const HIDDEN = {
+    position: "absolute",
+    left: "-10000px",
+    width: 1,
+    height: 1,
+    overflow: "hidden",
+};
+export function ApplicationForm(props) {
+    const { publishableKey, origin, analytics, fields = DEFAULT_FIELDS, labels, onSuccess, onError, className, submitLabel } = props;
+    const f = useApplicationForm({ publishableKey, origin, analytics });
+    if (f.state === "loading")
+        return _jsx("p", { children: "Loading\u2026" });
+    if (f.state === "error" && !f.config)
+        return _jsx("p", { children: f.error ?? "This form is unavailable." });
+    if (f.state === "sent")
+        return _jsx("p", { children: f.message });
+    const label = (name) => labels?.[name] ?? DEFAULT_LABELS[name];
+    return (_jsxs("form", { className: className, noValidate: true, onSubmit: (e) => {
+            e.preventDefault();
+            void f.submit().then((res) => {
+                // From the returned value, not from `f`: the state read here would be
+                // the one this render closed over, before the submission ran — and it
+                // carries the real reason, so a caller can tell a rejected field from
+                // a refused origin.
+                if (res.ok)
+                    onSuccess?.(res.message);
+                else
+                    onError?.(res.error);
+            });
+        }, children: [f.config?.companyName && _jsxs("h3", { children: ["Drive for ", f.config.companyName] }), fields.map((name) => {
+                const id = `fga-${name}`;
+                const fieldErrors = f.errors[name] ?? [];
+                return (_jsxs("div", { children: [_jsxs("label", { htmlFor: id, children: [label(name), REQUIRED.includes(name) ? " *" : ""] }), _jsx("input", { id: id, name: name, type: name === "email" ? "email" : name === "phone" ? "tel" : "text", value: f.values[name] ?? "", required: REQUIRED.includes(name), "aria-invalid": fieldErrors.length > 0 || undefined, "aria-describedby": fieldErrors.length > 0 ? `${id}-error` : undefined, onChange: (e) => f.setValue(name, e.target.value) }), fieldErrors.length > 0 && _jsx("p", { id: `${id}-error`, children: fieldErrors[0] })] }, name));
+            }), _jsx("input", { ...f.honeypotProps, tabIndex: -1, autoComplete: "off", "aria-hidden": "true", style: HIDDEN }), _jsxs("div", { children: [_jsx("input", { id: "fga-consent", type: "checkbox", checked: f.consentGranted, onChange: (e) => f.setConsentGranted(e.target.checked) }), _jsx("label", { htmlFor: "fga-consent", children: f.config?.consentText })] }), f.error && _jsx("p", { role: "alert", children: f.stale ? "This form has been updated. Please reload the page and try again." : f.error }), _jsx("button", { type: "submit", disabled: f.state === "sending", children: f.state === "sending" ? "Sending…" : (submitLabel ?? "Apply") })] }));
+}

package/dist/form/index.d.ts

@@ -0,0 +1,7 @@
+export { ApplicationForm } from "./ApplicationForm.js";
+export type { ApplicationFormProps, FieldName } from "./ApplicationForm.js";
+export { useApplicationForm } from "./useApplicationForm.js";
+export type { UseApplicationForm, UseApplicationFormOptions, FormState, SubmitOutcome } from "./useApplicationForm.js";
+export { IntakeError } from "../shared/client.js";
+export type { ApplicationValues, FieldErrors, FleegitalOptions, IntakeConfig, SubmitResult, EventSink, } from "../shared/client.js";
+export { visitorId } from "../shared/visitor.js";

package/dist/form/index.js

@@ -0,0 +1,4 @@
+export { ApplicationForm } from "./ApplicationForm.js";
+export { useApplicationForm } from "./useApplicationForm.js";
+export { IntakeError } from "../shared/client.js";
+export { visitorId } from "../shared/visitor.js";

package/dist/form/useApplicationForm.d.ts

@@ -0,0 +1,60 @@
+import { type ApplicationValues, type FieldErrors, type EventSink, type FleegitalOptions, type IntakeConfig } from "../shared/client.js";
+export type FormState = "loading" | "ready" | "sending" | "sent" | "error";
+export interface UseApplicationFormOptions extends FleegitalOptions {
+    /**
+     * Where to report the three funnel steps: the form became usable, the
+     * applicant typed something, the application was accepted. Pass the object
+     * `createAnalytics()` returned. Without it the form reports nothing, and
+     * the funnel columns in Fleegital stay empty — the page view is recorded
+     * either way, by the analytics package, but a page view is not an attempt.
+     */
+    analytics?: EventSink;
+}
+/** The result of one submission, carrying the reason when it failed. */
+export type SubmitOutcome = {
+    ok: true;
+    message: string;
+} | {
+    ok: false;
+    error: string;
+    fields?: FieldErrors;
+    stale: boolean;
+};
+export interface UseApplicationForm {
+    /** Null until the company's wording and branding have loaded. */
+    config: IntakeConfig | null;
+    state: FormState;
+    values: ApplicationValues;
+    setValue: <K extends keyof ApplicationValues>(field: K, value: ApplicationValues[K]) => void;
+    consentGranted: boolean;
+    setConsentGranted: (granted: boolean) => void;
+    /** Per-field messages from the server, cleared as soon as the field changes. */
+    errors: FieldErrors;
+    /** Whole-form message: a network failure, or the wording having changed. */
+    error: string | null;
+    /** True when the consent wording changed and the page must be reloaded. */
+    stale: boolean;
+    /** The server's own thank-you wording, once sent. */
+    message: string | null;
+    /**
+     * Returns what happened. The outcome is returned rather than only put in
+     * state because a caller that awaits this and then reads `state` reads the
+     * render it started from, not the one the submission produced.
+     */
+    submit: () => Promise<SubmitOutcome>;
+    /** Bind to a field no person can see; a value in it means a bot filled it. */
+    honeypotProps: {
+        name: string;
+        value: string;
+        onChange: (e: {
+            target: {
+                value: string;
+            };
+        }) => void;
+    };
+}
+/**
+ * The form without any markup, for carriers who want their own.
+ * `ApplicationForm` is this hook plus a plain, unstyled layout.
+ */
+export declare function useApplicationForm(options: UseApplicationFormOptions): UseApplicationForm;

package/dist/form/useApplicationForm.js

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { fetchIntakeConfig, submitApplication, IntakeError, } from "../shared/client.js";
+import { visitorId } from "../shared/visitor.js";
+/**
+ * The form without any markup, for carriers who want their own.
+ * `ApplicationForm` is this hook plus a plain, unstyled layout.
+ */
+export function useApplicationForm(options) {
+    const { publishableKey, origin, analytics } = options;
+    const [config, setConfig] = useState(null);
+    const [state, setState] = useState("loading");
+    const [values, setValues] = useState({ first_name: "" });
+    const [consentGranted, setConsentGranted] = useState(false);
+    const [errors, setErrors] = useState({});
+    const [error, setError] = useState(null);
+    const [stale, setStale] = useState(false);
+    const [message, setMessage] = useState(null);
+    const honeypot = useRef("");
+    // Each step is reported once per mounted form. A re-render is not a new
+    // attempt, and a second keystroke is not a second start.
+    const reported = useRef({ view: false, start: false });
+    // Held in a ref so that passing a fresh object every render — which a
+    // caller doing `analytics={createAnalytics(...)}` inline would — does not
+    // re-run the effect below and report the form as viewed again.
+    const sink = useRef(analytics);
+    sink.current = analytics;
+    useEffect(() => {
+        const ac = new AbortController();
+        setState("loading");
+        fetchIntakeConfig({ publishableKey, origin }, ac.signal)
+            .then((cfg) => {
+            setConfig(cfg);
+            setState("ready");
+            // Reported here rather than on mount: until the company's wording has
+            // loaded there is no form to have seen, only a spinner.
+            if (!reported.current.view) {
+                reported.current.view = true;
+                sink.current?.track("form_view");
+            }
+        })
+            .catch((e) => {
+            if (ac.signal.aborted)
+                return;
+            setError(e instanceof Error ? e.message : "This form is unavailable.");
+            setState("error");
+        });
+        return () => ac.abort();
+    }, [publishableKey, origin]);
+    const setValue = useCallback((field, value) => {
+        if (!reported.current.start) {
+            reported.current.start = true;
+            sink.current?.track("form_start");
+        }
+        setValues((v) => ({ ...v, [field]: value }));
+        // A message about what the applicant just changed is already out of date.
+        setErrors((e) => (e[field] ? { ...e, [field]: [] } : e));
+    }, []);
+    const submit = useCallback(async () => {
+        if (!config)
+            return { ok: false, error: "This form is not ready yet.", stale: false };
+        if (state === "sending")
+            return { ok: false, error: "Already sending.", stale: false };
+        setState("sending");
+        setError(null);
+        setErrors({});
+        try {
+            const res = await submitApplication({
+                publishableKey,
+                origin,
+                values,
+                consentGranted,
+                consentVersion: config.consentVersion,
+                visitorId: visitorId(),
+                honeypot: honeypot.current,
+            });
+            setMessage(res.message);
+            setState("sent");
+            // Only on acceptance. A rejected submission is not a submission, and
+            // counting it would make the funnel wider at the bottom than the top.
+            sink.current?.track("form_submit");
+            return { ok: true, message: res.message };
+        }
+        catch (e) {
+            setState("ready");
+            if (e instanceof IntakeError) {
+                if (e.fields)
+                    setErrors(e.fields);
+                setStale(e.stale);
+                setError(e.message);
+                return e.fields
+                    ? { ok: false, error: e.message, fields: e.fields, stale: e.stale }
+                    : { ok: false, error: e.message, stale: e.stale };
+            }
+            const msg = "Something went wrong. Please try again.";
+            setError(msg);
+            return { ok: false, error: msg, stale: false };
+        }
+    }, [config, state, publishableKey, origin, values, consentGranted]);
+    const honeypotProps = useMemo(() => ({
+        name: "company_website",
+        value: honeypot.current,
+        onChange: (e) => {
+            honeypot.current = e.target.value;
+        },
+    }), []);
+    return {
+        config, state, values, setValue, consentGranted, setConsentGranted,
+        errors, error, stale, message, submit, honeypotProps,
+    };
+}

package/dist/shared/client.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Everything the package knows about reaching Fleegital.
+ *
+ * One rule shapes this file: a carrier's developer only ever sees our own
+ * domain. The backend host is never printed, never configurable by accident,
+ * and never reachable from a carrier page — `origin` exists for local
+ * development and for carriers we put behind their own apply subdomain.
+ */
+/** Where the intake endpoint lives unless the caller says otherwise. */
+export declare const DEFAULT_ORIGIN = "https://www.fleegital.app";
+/**
+ * The door this package submits through. It is checked exactly like the script
+ * tag — same publishable key, same origin allowlist — and named apart so the
+ * Website applications screen can show how many carriers installed the package.
+ */
+export declare const DOOR: "npm";
+export interface FleegitalOptions {
+    /** `pk_…`, from Settings → Recruiting configuration → Website applications. */
+    publishableKey: string;
+    /** Override only for local development or a carrier-specific apply domain. */
+    origin?: string;
+}
+/** What the form needs from the server before it can render. */
+export interface IntakeConfig {
+    companyName: string | null;
+    consentText: string;
+    /** Echoed back on submit; a mismatch means the wording changed under us. */
+    consentVersion: string;
+    primaryColor: string | null;
+    /** Already rewritten to our own domain by the server. */
+    logoUrl: string | null;
+}
+/** A field-level rejection, as the endpoint reports it. */
+export type FieldErrors = Record<string, string[]>;
+export declare class IntakeError extends Error {
+    readonly status: number;
+    readonly fields: FieldErrors | undefined;
+    /** True when the form must be reloaded: the consent wording changed. */
+    readonly stale: boolean;
+    constructor(message: string, status: number, fields?: FieldErrors);
+}
+/** Reads the company name, consent wording and brand colour for a key. */
+export declare function fetchIntakeConfig(options: FleegitalOptions, signal?: AbortSignal): Promise<IntakeConfig>;
+/** The answers one applicant gave. Every field is optional but first name. */
+export interface ApplicationValues {
+    first_name: string;
+    last_name?: string;
+    phone?: string;
+    email?: string;
+    cdl_class?: string;
+    experience_years?: string;
+    position?: string;
+    location?: string;
+    notes?: string;
+}
+/**
+ * What the endpoint tells a carrier's page, which is deliberately very little.
+ *
+ * There is no lead id and no outcome here, and that is on purpose: an accepted
+ * application, one held for review, and one that tripped the spam trap all get
+ * the same answer, so a submitter cannot learn which happened. Anything a
+ * recruiter needs is in the app.
+ */
+export interface SubmitResult {
+    /** The wording to show the applicant, as the server phrased it. */
+    message: string;
+}
+export interface SubmitArgs extends FleegitalOptions {
+    values: ApplicationValues;
+    consentGranted: boolean;
+    consentVersion: string;
+    /** Anonymous first-party id, so the lead can be traced to the first visit. */
+    visitorId?: string | undefined;
+    /** Spam trap: the value of a field a person never sees. Must stay empty. */
+    honeypot?: string;
+    pageUrl?: string;
+    signal?: AbortSignal;
+}
+export declare function submitApplication(args: SubmitArgs): Promise<SubmitResult>;
+/** The four names the server counts. A fifth would be stored and never read. */
+export declare const ANALYTICS_EVENTS: readonly ["page_view", "form_view", "form_start", "form_submit"];
+export type AnalyticsEventName = (typeof ANALYTICS_EVENTS)[number];
+/**
+ * Somewhere to report a funnel event. `Analytics` satisfies it structurally,
+ * so the form can report into it without importing the analytics module —
+ * a carrier who only installs the form ships none of the analytics code.
+ */
+export interface EventSink {
+    track: (event: AnalyticsEventName, path?: string) => void;
+}
+/** One event, in the shape the endpoint reads. */
+export interface AnalyticsEvent {
+    event_name: AnalyticsEventName;
+    path: string;
+    visitor_id: string;
+    session_id?: string | undefined;
+    referrer_host?: string | undefined;
+    device?: string | undefined;
+    utm?: Record<string, string> | undefined;
+    /** ISO 8601. The server clamps it into the last two days. */
+    occurred_at: string;
+}
+/** The server's answer, which says nothing a caller can act on. */
+export interface SendEventsResult {
+    accepted: number;
+    dropped: number;
+}
+/** The endpoint accepts at most this many events in one request. */
+export declare const MAX_BATCH = 50;
+/**
+ * Sends a batch. Never throws and never rejects: a page view is not worth
+ * breaking, retrying or logging on someone else's website, and the endpoint
+ * answers 202 for every outcome anyway, so there is nothing to branch on.
+ *
+ * `keepalive` lets the request outlive the page, which is the whole point
+ * when a tab is closing. sendBeacon would be the other way, but it cannot
+ * set the key header, and moving the key into the URL to suit it would put
+ * it in every proxy log for no gain.
+ */
+export declare function sendEvents(options: FleegitalOptions, events: AnalyticsEvent[], keepalive?: boolean): Promise<SendEventsResult | undefined>;

package/dist/shared/client.js

@@ -0,0 +1,107 @@
+/**
+ * Everything the package knows about reaching Fleegital.
+ *
+ * One rule shapes this file: a carrier's developer only ever sees our own
+ * domain. The backend host is never printed, never configurable by accident,
+ * and never reachable from a carrier page — `origin` exists for local
+ * development and for carriers we put behind their own apply subdomain.
+ */
+/** Where the intake endpoint lives unless the caller says otherwise. */
+export const DEFAULT_ORIGIN = "https://www.fleegital.app";
+/**
+ * The door this package submits through. It is checked exactly like the script
+ * tag — same publishable key, same origin allowlist — and named apart so the
+ * Website applications screen can show how many carriers installed the package.
+ */
+export const DOOR = "npm";
+export class IntakeError extends Error {
+    constructor(message, status, fields) {
+        super(message);
+        this.name = "IntakeError";
+        this.status = status;
+        this.fields = fields;
+        this.stale = status === 409;
+    }
+}
+const endpoint = (origin) => `${(origin ?? DEFAULT_ORIGIN).replace(/\/+$/, "")}/api/intake`;
+async function readError(res) {
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+        /* a proxy or a network device answered instead of the API */
+    }
+    const first = body.fields && Object.values(body.fields)[0]?.[0];
+    return new IntakeError(first ?? body.error ?? "The application could not be sent.", res.status, body.fields);
+}
+/** Reads the company name, consent wording and brand colour for a key. */
+export async function fetchIntakeConfig(options, signal) {
+    const res = await fetch(`${endpoint(options.origin)}?key=${encodeURIComponent(options.publishableKey)}`, {
+        signal,
+    });
+    if (!res.ok)
+        throw await readError(res);
+    const cfg = (await res.json());
+    return {
+        companyName: cfg.company_name ?? null,
+        consentText: String(cfg.consent_text ?? ""),
+        consentVersion: String(cfg.consent_version ?? ""),
+        primaryColor: cfg.primary_color ?? null,
+        logoUrl: cfg.logo_url ?? null,
+    };
+}
+export async function submitApplication(args) {
+    const res = await fetch(endpoint(args.origin), {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "x-fleegital-key": args.publishableKey },
+        signal: args.signal,
+        body: JSON.stringify({
+            door: DOOR,
+            page_url: args.pageUrl ?? (typeof location === "undefined" ? undefined : location.href),
+            company_website: args.honeypot ?? "",
+            visitor_id: args.visitorId,
+            consent: { granted: args.consentGranted, version: args.consentVersion },
+            ...args.values,
+        }),
+    });
+    if (!res.ok)
+        throw await readError(res);
+    const body = (await res.json());
+    return { message: body.message ?? "Thank you. Your application was received." };
+}
+/* ------------------------------------------------------------------ *
+ * Analytics transport
+ * ------------------------------------------------------------------ */
+/** The four names the server counts. A fifth would be stored and never read. */
+export const ANALYTICS_EVENTS = ["page_view", "form_view", "form_start", "form_submit"];
+/** The endpoint accepts at most this many events in one request. */
+export const MAX_BATCH = 50;
+const analyticsEndpoint = (origin) => `${(origin ?? DEFAULT_ORIGIN).replace(/\/+$/, "")}/api/analytics`;
+/**
+ * Sends a batch. Never throws and never rejects: a page view is not worth
+ * breaking, retrying or logging on someone else's website, and the endpoint
+ * answers 202 for every outcome anyway, so there is nothing to branch on.
+ *
+ * `keepalive` lets the request outlive the page, which is the whole point
+ * when a tab is closing. sendBeacon would be the other way, but it cannot
+ * set the key header, and moving the key into the URL to suit it would put
+ * it in every proxy log for no gain.
+ */
+export async function sendEvents(options, events, keepalive = false) {
+    if (events.length === 0)
+        return { accepted: 0, dropped: 0 };
+    try {
+        const res = await fetch(analyticsEndpoint(options.origin), {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "x-fleegital-key": options.publishableKey },
+            body: JSON.stringify({ events: events.slice(0, MAX_BATCH) }),
+            keepalive,
+        });
+        const body = (await res.json());
+        return { accepted: body.accepted ?? 0, dropped: body.dropped ?? 0 };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/shared/device.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Which of the three kinds of device this is, or nothing.
+ *
+ * The server accepts only `mobile`, `tablet` and `desktop` and drops anything
+ * else, so guessing wrongly costs the field rather than the event. Returning
+ * undefined is a fine answer and better than a confident wrong one.
+ *
+ * Deliberately not a user-agent parsing library: those are large, need
+ * constant updating, and are a fingerprinting surface. This asks the browser
+ * where the browser will say, and falls back to two coarse patterns.
+ */
+export type Device = "mobile" | "tablet" | "desktop";
+export declare function device(): Device | undefined;

package/dist/shared/device.js

@@ -0,0 +1,33 @@
+export function device() {
+    if (typeof navigator === "undefined")
+        return undefined;
+    try {
+        const ua = navigator.userAgent || "";
+        // iPadOS reports itself as a Mac; the touch points give it away.
+        const iPad = /iPad/.test(ua) ||
+            (/Macintosh/.test(ua) && typeof navigator.maxTouchPoints === "number" && navigator.maxTouchPoints > 1);
+        if (iPad)
+            return "tablet";
+        // Android puts "Mobile" in the string for phones and leaves it out for tablets.
+        if (/Android/.test(ua))
+            return /Mobile/.test(ua) ? "mobile" : "tablet";
+        // Named devices before the coarse signal. `userAgentData.mobile` is a
+        // single boolean that Chromium answers from its own build, not from the
+        // user-agent string, so it reports a spoofed or overridden phone as a
+        // desktop — which is how this function first got an iPhone wrong.
+        if (/iPhone|iPod|Windows Phone/.test(ua))
+            return "mobile";
+        if (/Tablet|PlayBook|Silk|Kindle/.test(ua))
+            return "tablet";
+        // Then let the browser answer where it will.
+        const uaData = navigator.userAgentData;
+        if (uaData && typeof uaData.mobile === "boolean")
+            return uaData.mobile ? "mobile" : "desktop";
+        if (/Mobi/.test(ua))
+            return "mobile";
+        return "desktop";
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/shared/session.d.ts

@@ -0,0 +1,10 @@
+/** The five tags the server stores. Anything else in the URL is ignored. */
+export declare const UTM_PARAMS: readonly ["source", "medium", "campaign", "content", "term"];
+export type Utm = Partial<Record<(typeof UTM_PARAMS)[number], string>>;
+/** The id for this visit, creating one on first use. */
+export declare function sessionId(): string | undefined;
+/**
+ * The campaign this visit arrived on: taken from the URL the first time any
+ * utm_* parameter appears, and kept for the rest of the visit.
+ */
+export declare function visitUtm(): Utm;

package/dist/shared/session.js

@@ -0,0 +1,99 @@
+/**
+ * Per-visit state: a session id, and the campaign the visit arrived on.
+ *
+ * sessionStorage, not localStorage: this is meant to end when the tab does.
+ * Every access is guarded for the same reason as visitor.ts — in a private
+ * window or with site data blocked the accessor itself throws, and analytics
+ * must never be the reason a carrier's page breaks.
+ *
+ * The campaign is remembered for the whole visit rather than read fresh on
+ * each page. A visitor who arrives from an ad and then reads three pages
+ * should count as three pages for that campaign; reading the URL each time
+ * would credit the landing page and lose the rest.
+ */
+const SESSION_KEY = "fga_sid";
+const UTM_KEY = "fga_utm";
+/** The five tags the server stores. Anything else in the URL is ignored. */
+export const UTM_PARAMS = ["source", "medium", "campaign", "content", "term"];
+function read(key) {
+    try {
+        return window.sessionStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function write(key, value) {
+    try {
+        window.sessionStorage.setItem(key, value);
+    }
+    catch {
+        /* storage is closed; the visit simply carries no id */
+    }
+}
+function makeId() {
+    const bytes = new Uint8Array(12);
+    const c = typeof crypto !== "undefined" ? crypto : undefined;
+    if (c && typeof c.getRandomValues === "function")
+        c.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let out = "s";
+    for (const b of bytes)
+        out += b.toString(36).padStart(2, "0");
+    return out.slice(0, 32);
+}
+/** The id for this visit, creating one on first use. */
+export function sessionId() {
+    if (typeof window === "undefined")
+        return undefined;
+    const found = read(SESSION_KEY);
+    if (found)
+        return found;
+    const created = makeId();
+    write(SESSION_KEY, created);
+    return created;
+}
+/**
+ * The campaign this visit arrived on: taken from the URL the first time any
+ * utm_* parameter appears, and kept for the rest of the visit.
+ */
+export function visitUtm() {
+    if (typeof window === "undefined")
+        return {};
+    let fromUrl = {};
+    try {
+        const q = new URLSearchParams(window.location.search);
+        for (const p of UTM_PARAMS) {
+            const v = q.get("utm_" + p);
+            if (v)
+                fromUrl[p] = v.slice(0, 200);
+        }
+    }
+    catch {
+        fromUrl = {};
+    }
+    if (Object.keys(fromUrl).length > 0) {
+        write(UTM_KEY, JSON.stringify(fromUrl));
+        return fromUrl;
+    }
+    const stored = read(UTM_KEY);
+    if (!stored)
+        return {};
+    try {
+        const parsed = JSON.parse(stored);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        const out = {};
+        for (const p of UTM_PARAMS) {
+            const v = parsed[p];
+            if (typeof v === "string" && v)
+                out[p] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/shared/visitor.d.ts

@@ -0,0 +1,2 @@
+/** The id for this browser, creating one on first use. Undefined if storage is closed. */
+export declare function visitorId(): string | undefined;

package/dist/shared/visitor.js

@@ -0,0 +1,41 @@
+/**
+ * An anonymous id for this browser, so an application can be traced back to the
+ * visit it came from.
+ *
+ * localStorage only: no cookie, nothing sent to a third party, and nothing that
+ * identifies a person. Every read and write is guarded, because in a private
+ * window or with site data blocked the accessor itself throws — and a form that
+ * fails to submit is a worse outcome than a lead with no attribution. When
+ * storage is unavailable the submission simply carries no id.
+ */
+const KEY = "fga_vid";
+function make() {
+    const bytes = new Uint8Array(12);
+    const c = typeof crypto !== "undefined" ? crypto : undefined;
+    if (c && typeof c.getRandomValues === "function")
+        c.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let out = "v";
+    for (const b of bytes)
+        out += b.toString(36).padStart(2, "0");
+    // The server accepts /^[A-Za-z0-9_-]{8,64}$/; this is 25 characters.
+    return out.slice(0, 32);
+}
+/** The id for this browser, creating one on first use. Undefined if storage is closed. */
+export function visitorId() {
+    if (typeof window === "undefined")
+        return undefined;
+    try {
+        const found = window.localStorage.getItem(KEY);
+        if (found)
+            return found;
+        const created = make();
+        window.localStorage.setItem(KEY, created);
+        return created;
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@fleegital/web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The driver application form and website analytics for carriers running Fleegital.",
+  "license": "MIT",
+  "author": "Fleegital",
+  "homepage": "https://github.com/fleegital/fleegital-web#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fleegital/fleegital-web.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fleegital/fleegital-web/issues"
+  },
+  "keywords": [
+    "fleegital",
+    "trucking",
+    "recruiting",
+    "cdl",
+    "application-form",
+    "analytics"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./form": {
+      "types": "./dist/form/index.d.ts",
+      "import": "./dist/form/index.js"
+    },
+    "./analytics": {
+      "types": "./dist/analytics/index.d.ts",
+      "import": "./dist/analytics/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.1",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}