@evinvest/kitstart 0.1.0

package/dist/core/antispam.js

@@ -0,0 +1,90 @@
+/**
+ * Three cheap barriers, none of which needs the visitor to run a script — the
+ * form has to work before any JavaScript arrives, so a challenge widget is not
+ * an option. A rejected submission is answered exactly like an accepted one,
+ * so a bot learns nothing from the response.
+ */
+/**
+ * The field a human never sees and a form-filling bot fills. A neutral name:
+ * a browser's autofill knows `website`, `url` or `company` and would fill the
+ * trap for a real person.
+ */
+export const HONEYPOT_FIELD = "hp_ref";
+/** The trap's name on pages cached before it was renamed; still read. */
+export const LEGACY_HONEYPOT_FIELDS = ["website"];
+/** When the form was rendered, in ms since the epoch. */
+export const RENDERED_AT_FIELD = "t";
+/** Faster than this from render to submit is a script, not a person. */
+export const MIN_FILL_MS = 3_000;
+/** A render time this far ahead of the clock was forged. */
+const MAX_SKEW_MS = 60_000;
+export function checkTiming(renderedAt, now) {
+    const t = renderedAt === null || renderedAt.trim() === "" ? Number.NaN : Number(renderedAt);
+    if (!Number.isFinite(t) || t - now > MAX_SKEW_MS)
+        return "too-fast";
+    return now - t < MIN_FILL_MS ? "too-fast" : "ok";
+}
+/** How many distinct keys a limiter tracks before new ones share one bucket. */
+export const RATE_LIMIT_MAX_KEYS = 10_000;
+/** The shared bucket keys past the cap count against. */
+export const RATE_LIMIT_OVERFLOW_KEY = "\u0000overflow";
+const PRUNE_EVERY_MS = 1_000;
+/**
+ * A fixed-window counter per client address, in memory. Per process by design:
+ * it is a speed bump for one bot hammering one pod, not an accounting system,
+ * and a restart forgetting it costs nothing.
+ *
+ * Bounded: past `maxKeys` distinct addresses in one window, new ones count
+ * against one shared bucket — a flood of forged addresses throttles itself
+ * instead of growing the map. Expired windows are swept at most once a second.
+ */
+export class RateLimiter {
+    limit;
+    windowMs;
+    maxKeys;
+    hits = new Map();
+    lastPrune = Number.NEGATIVE_INFINITY;
+    constructor(limit, windowMs, maxKeys = RATE_LIMIT_MAX_KEYS) {
+        this.limit = limit;
+        this.windowMs = windowMs;
+        this.maxKeys = maxKeys;
+    }
+    /** `true` if this hit is allowed. */
+    hit(key, now) {
+        this.prune(now);
+        const bucket = this.hits.has(key) || this.hits.size < this.maxKeys ? key : RATE_LIMIT_OVERFLOW_KEY;
+        const entry = this.hits.get(bucket);
+        if (!entry || now - entry.start >= this.windowMs) {
+            this.hits.set(bucket, { start: now, count: 1 });
+            return true;
+        }
+        entry.count += 1;
+        return entry.count <= this.limit;
+    }
+    /** Distinct buckets held now, for tests and diagnostics. */
+    get size() {
+        return this.hits.size;
+    }
+    prune(now) {
+        if (now - this.lastPrune < PRUNE_EVERY_MS)
+            return;
+        this.lastPrune = now;
+        for (const [key, entry] of this.hits) {
+            if (now - entry.start >= this.windowMs)
+                this.hits.delete(key);
+        }
+    }
+}
+/**
+ * The barriers in their order. Every submission past the honeypot spends the
+ * limiter — a script that omits the render stamp must not get unlimited
+ * `too-fast` rows — and the verdict ranks the server's own evidence first:
+ * honeypot, then rate-limited, then the client's stamp (too-fast).
+ */
+export function screen(input) {
+    if (input.honeypot !== null && input.honeypot.trim() !== "")
+        return "honeypot";
+    if (!input.limiter.hit(input.clientKey, input.now))
+        return "rate-limited";
+    return checkTiming(input.renderedAt, input.now);
+}

package/dist/core/content.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The copy contract the machinery reads. A brand's `Text` extends
+ * `CoreText` and adds everything its own sections say; a shared widget takes
+ * only its slice (`StatusCopy`, `QuoteFormCopy`, `PageMetaCopy`…), so a brand
+ * can reword its hero without the status screen's type noticing, and a
+ * widget's signature says which words it can print.
+ *
+ * `F` is the brand's facts — the phone, the place, the prices a sentence may
+ * quote. Prose that quotes a fact takes it as an argument instead of spelling
+ * it out, so the number in the sentence and the number on the card are one.
+ */
+/** A sentence that quotes a fact. */
+export type Said<F> = (f: F) => string;
+/** What `<head>`, the OG card and the breadcrumbs read for one page. */
+export interface PageMetaCopy<F> {
+    /** `<title>`, the OG title and the breadcrumb label. */
+    title: Said<F>;
+    /** Read by `<head>`, the OG card and the sitemap — one field, three readers. */
+    description: Said<F>;
+}
+export type StatusAction = "call" | "home" | "retry";
+/** The 404, the 500 and the post-submit confirmation. */
+export interface StatusCopy<F> {
+    code: string;
+    /** The `<title>`: these pages are `noindex` and carry no page meta. */
+    title: string;
+    eyebrow: string;
+    /** Split at the accented half, which is how the design draws it. */
+    headline: readonly [string, string];
+    body: Said<F>;
+    primary: StatusAction;
+    secondary: StatusAction;
+}
+/** The quote form's frame; the fields a brand asks for label themselves. */
+export interface QuoteFormCopy<F> {
+    title: string;
+    lede: string;
+    submit: string;
+    privacy: string;
+    reassurance: Said<F>;
+    /** The honeypot's label — read only by a bot filling every field. */
+    honeypotLabel: string;
+}
+/** Every string the shared machinery prints, per language. */
+export interface CoreText<P extends string, F> {
+    pages: Record<P, PageMetaCopy<F>>;
+    quoteForm: QuoteFormCopy<F>;
+    notFound: StatusCopy<F>;
+    serverError: StatusCopy<F>;
+    thanks: StatusCopy<F>;
+    /** The accessible name of every `tel:` link. */
+    callLabel: Said<F>;
+    whatsappLabel: string;
+    /** The same channel where only a word fits. */
+    whatsappShort: string;
+    whatsappMessage: Said<F>;
+    /** The one CTA label where only a word fits. */
+    ctaShort: string;
+    backHome: string;
+    tryAgain: string;
+    /** The offer's terms, compressed under a status screen. */
+    statusStrip: readonly string[];
+    langName: string;
+    /**
+     * The business's registration facts (SIRET, insurer…) as short items — the
+     * status screen prints them under its offer strip.
+     */
+    facts: (f: F) => readonly string[];
+}
+/** What the status screen prints besides its own `StatusCopy`. */
+export type StatusScreenText<F> = Pick<CoreText<string, F>, "callLabel" | "backHome" | "tryAgain" | "statusStrip" | "facts">;
+/** What the mobile call bar prints. */
+export type CallBarText<F> = Pick<CoreText<string, F>, "callLabel" | "whatsappMessage" | "whatsappShort" | "ctaShort">;
+/**
+ * What a widget needs to say something: the language, its slice of the words,
+ * and the facts they quote. A brand's full `Copy` is assignable to any slice.
+ */
+export interface CopySlice<L extends string, T, F> {
+    locale: L;
+    t: T;
+    f: F;
+}

package/dist/core/content.js

@@ -0,0 +1,12 @@
+/**
+ * The copy contract the machinery reads. A brand's `Text` extends
+ * `CoreText` and adds everything its own sections say; a shared widget takes
+ * only its slice (`StatusCopy`, `QuoteFormCopy`, `PageMetaCopy`…), so a brand
+ * can reword its hero without the status screen's type noticing, and a
+ * widget's signature says which words it can print.
+ *
+ * `F` is the brand's facts — the phone, the place, the prices a sentence may
+ * quote. Prose that quotes a fact takes it as an argument instead of spelling
+ * it out, so the number in the sentence and the number on the card are one.
+ */
+export {};

package/dist/core/lead.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The lead as data. Every landing asks for a subject (what the job is), a
+ * locality (where to go) and a mobile (how to answer); what else it asks for
+ * is the brand's `extras`, and what it refuses is the brand's `validate`. The
+ * funnel's order — validate → screen → insert → deferred notify — is the
+ * machinery's, not the schema's.
+ *
+ * `Lead.subject` is a plain `string` (a stale form's value is still a job) and
+ * `LeadSchema.wire` names the posted fields (a page cached before a rename
+ * still delivers) — both deliberate departures from the first design.
+ */
+/** Why a submission was kept but not acted on. `null` is a clean lead. */
+export type SpamVerdict = "honeypot" | "too-fast" | "rate-limited";
+/**
+ * One more field a brand's form asks for, capped at its own `max` characters —
+ * not at `MAX_FIELD`, which caps the core fields: a free-text note may be longer.
+ */
+export interface LeadExtra {
+    name: string;
+    max: number;
+}
+/**
+ * The form field each core value is posted under. Brand config, not a
+ * constant: a page cached before a rename still posts the old names, and a
+ * lead from it is still a customer.
+ */
+export interface LeadWire {
+    subject: string;
+    locality: string;
+    mobile: string;
+}
+export interface LeadSchema<S extends string> {
+    /** What the form's subject control offers, in order. */
+    subjects: readonly S[];
+    wire: LeadWire;
+    extras?: readonly LeadExtra[];
+    /**
+     * The one rule worth enforcing, as a reason for the log (never rendered), or
+     * `null` to accept. Absent → every candidate is a lead.
+     */
+    validate?: (lead: LeadCandidate) => string | null;
+}
+/**
+ * A submitted lead. Values are trimmed and capped but not otherwise parsed: a
+ * lead that cannot be fully validated is still a lead, and rejecting it loses
+ * a customer to protect a column type. `subject` is kept as posted even when
+ * it is not one of `subjects` — a stale form's value is still a job.
+ */
+export interface Lead {
+    subject: string;
+    locality: string;
+    mobile: string;
+    extras: Readonly<Record<string, string>>;
+    /** The place it was submitted from — its slug — or `null` when unknown. */
+    placeSlug: string | null;
+    spamVerdict: SpamVerdict | null;
+}
+export type LeadCandidate = Omit<Lead, "spamVerdict">;
+/**
+ * The port the funnel writes through — the commit point. `insert` resolves
+ * with the row's id only once the lead is durable; a rejection is a lead the
+ * visitor must not be thanked for. Async because not every adapter is
+ * in-process: SQLite answers synchronously, a network database does not.
+ *
+ * An adapter migrates its storage forward on open, versioned by
+ * `LEAD_SCHEMA_VERSION`, and must pass the shared contract suite
+ * (`@evinvest/kitstart/testing`) before `LEADS_DB_URL` may select it.
+ */
+export interface LeadStore {
+    insert(lead: Lead): Promise<number>;
+    count(): Promise<number>;
+    /** The schema version the storage stands at after opening. */
+    schemaVersion(): Promise<number>;
+    /** Resolves while the store can take a lead; rejects with why it cannot. */
+    health(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * The lead schema's version, shared by every adapter: 1 the Rust server's
+ * table (`job`, `zip`, `mobile`, `at`), 2 + the place, 3 + the spam verdict,
+ * 4 + the brand's extras. Append only.
+ */
+export declare const LEAD_SCHEMA_VERSION = 4;
+/** A field is capped, not rejected: a long answer is still a customer. */
+export declare const MAX_FIELD = 200;
+/** The candidate a form posted, read through the schema's field names. */
+export declare function readCandidate(schema: LeadSchema<string>, form: FormData, placeSlug: string | null): LeadCandidate;
+export declare function validateCandidate(schema: LeadSchema<string>, lead: LeadCandidate): string | null;

package/dist/core/lead.js

@@ -0,0 +1,42 @@
+/**
+ * The lead as data. Every landing asks for a subject (what the job is), a
+ * locality (where to go) and a mobile (how to answer); what else it asks for
+ * is the brand's `extras`, and what it refuses is the brand's `validate`. The
+ * funnel's order — validate → screen → insert → deferred notify — is the
+ * machinery's, not the schema's.
+ *
+ * `Lead.subject` is a plain `string` (a stale form's value is still a job) and
+ * `LeadSchema.wire` names the posted fields (a page cached before a rename
+ * still delivers) — both deliberate departures from the first design.
+ */
+/**
+ * The lead schema's version, shared by every adapter: 1 the Rust server's
+ * table (`job`, `zip`, `mobile`, `at`), 2 + the place, 3 + the spam verdict,
+ * 4 + the brand's extras. Append only.
+ */
+export const LEAD_SCHEMA_VERSION = 4;
+/** A field is capped, not rejected: a long answer is still a customer. */
+export const MAX_FIELD = 200;
+function field(form, name, max) {
+    const value = form.get(name);
+    return typeof value === "string" ? value.trim().slice(0, max) : null;
+}
+/** The candidate a form posted, read through the schema's field names. */
+export function readCandidate(schema, form, placeSlug) {
+    const extras = {};
+    for (const extra of schema.extras ?? []) {
+        const value = field(form, extra.name, extra.max);
+        if (value)
+            extras[extra.name] = value;
+    }
+    return {
+        subject: field(form, schema.wire.subject, MAX_FIELD) ?? "",
+        locality: field(form, schema.wire.locality, MAX_FIELD) ?? "",
+        mobile: field(form, schema.wire.mobile, MAX_FIELD) ?? "",
+        extras,
+        placeSlug,
+    };
+}
+export function validateCandidate(schema, lead) {
+    return schema.validate?.(lead) ?? null;
+}

package/dist/core/memo.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `fn` memoised per key for the life of the process, the pending promise
+ * included, so concurrent first requests share one computation. A rejection is
+ * forgotten, so the next caller retries instead of inheriting the failure.
+ *
+ * Unbounded by design: callers pass only keys drawn from a closed set.
+ */
+export declare function memoByKey<T>(fn: (key: string) => Promise<T>): (key: string) => Promise<T>;

package/dist/core/memo.js

@@ -0,0 +1,19 @@
+/**
+ * `fn` memoised per key for the life of the process, the pending promise
+ * included, so concurrent first requests share one computation. A rejection is
+ * forgotten, so the next caller retries instead of inheriting the failure.
+ *
+ * Unbounded by design: callers pass only keys drawn from a closed set.
+ */
+export function memoByKey(fn) {
+    const cache = new Map();
+    return key => {
+        let hit = cache.get(key);
+        if (!hit) {
+            hit = fn(key);
+            cache.set(key, hit);
+            hit.catch(() => cache.delete(key));
+        }
+        return hit;
+    };
+}

package/dist/core/place/index.d.ts

@@ -0,0 +1,5 @@
+export { servedLocalities, storefrontOf, type DayOfWeek, type Geo, type OpeningHours, type Place, type PostalAddress, type Presence, type Rating, type ServiceArea, } from "./types.js";
+export { isPublished, publicationGaps, SERVICE_AREA_GATE, STOREFRONT_GATE, type PublicationField, type PublicationPolicy, } from "./publication.js";
+export { freshRating, parseInstant, RATING_MAX_AGE_DAYS } from "./rating.js";
+export { mergeLive, parsePlaceLive, type PlaceLive } from "./live.js";
+export { createPlaceView, placeHref, placeOrigin, placeUrl, siteOrigin, type LinkBase, type LinkMode, type OriginFacts, type PlaceView, } from "./view.js";

package/dist/core/place/index.js

@@ -0,0 +1,5 @@
+export { servedLocalities, storefrontOf, } from "./types.js";
+export { isPublished, publicationGaps, SERVICE_AREA_GATE, STOREFRONT_GATE, } from "./publication.js";
+export { freshRating, parseInstant, RATING_MAX_AGE_DAYS } from "./rating.js";
+export { mergeLive, parsePlaceLive } from "./live.js";
+export { createPlaceView, placeHref, placeOrigin, placeUrl, siteOrigin, } from "./view.js";

package/dist/core/place/live.d.ts

@@ -0,0 +1,30 @@
+import type { Geo, OpeningHours, Place, PostalAddress, Rating, ServiceArea } from "./types.js";
+/**
+ * The live half of a place, as `GET <source>/locations/<slug>` answers it.
+ * Every field is optional: whatever the source leaves out, the baked config
+ * supplies. Validated here rather than cast — a response is a promise from
+ * another service, not a type. The wire shape is the source's own:
+ * `serviceArea` is a list of commune names.
+ */
+export interface PlaceLive<L extends string> {
+    phone?: string;
+    whatsapp?: string;
+    address?: Omit<PostalAddress, "region" | "country">;
+    geo?: Geo;
+    storefrontPhoto?: string;
+    landmark?: Readonly<Record<L, string>>;
+    serviceArea?: readonly ServiceArea[];
+    hours?: readonly OpeningHours[];
+    rating?: Rating;
+}
+/**
+ * Drops what does not validate instead of failing the page on one bad field.
+ * A landmark counts only when it is given in every one of `locales`.
+ */
+export declare function parsePlaceLive<L extends string>(body: unknown, locales: readonly L[]): PlaceLive<L>;
+/**
+ * The live fields over the baked ones. A service-area place takes none of the
+ * storefront's: an address, a pin or a photo from the source would give it a
+ * front it does not have.
+ */
+export declare function mergeLive<L extends string>(baked: Place<L>, live: PlaceLive<L>): Place<L>;

package/dist/core/place/live.js

@@ -0,0 +1,132 @@
+import { parseInstant } from "./rating.js";
+const DAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+const TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const str = (v) => (typeof v === "string" && v.trim() !== "" ? v : undefined);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const isDay = (d) => DAYS.some(day => day === d);
+function hours(v) {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = [];
+    for (const row of v) {
+        if (!isObject(row) || !Array.isArray(row.days))
+            return undefined;
+        const days = row.days.filter(isDay);
+        const opens = str(row.opens);
+        const closes = str(row.closes);
+        if (days.length !== row.days.length || !opens || !closes || !TIME.test(opens) || !TIME.test(closes)) {
+            return undefined;
+        }
+        out.push({ days, opens, closes });
+    }
+    return out;
+}
+function rating(v) {
+    if (!isObject(v))
+        return undefined;
+    const value = num(v.value);
+    const count = num(v.count);
+    const fetchedAt = str(v.fetchedAt);
+    if (value === undefined || count === undefined || !fetchedAt || parseInstant(fetchedAt) === null)
+        return undefined;
+    if (value < 1 || value > 5 || count < 0)
+        return undefined;
+    return { value, count, fetchedAt };
+}
+function httpsUrl(v) {
+    const s = str(v);
+    if (!s)
+        return undefined;
+    try {
+        return new URL(s).protocol === "https:" ? s : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function landmark(v, locales) {
+    if (!isObject(v))
+        return undefined;
+    const out = {};
+    for (const locale of locales) {
+        const text = str(v[locale]);
+        if (!text)
+            return undefined;
+        out[locale] = text;
+    }
+    return isComplete(out, locales) ? out : undefined;
+}
+function isComplete(record, locales) {
+    return locales.every(locale => typeof record[locale] === "string");
+}
+/**
+ * Drops what does not validate instead of failing the page on one bad field.
+ * A landmark counts only when it is given in every one of `locales`.
+ */
+export function parsePlaceLive(body, locales) {
+    if (!isObject(body))
+        throw new Error("live location: body is not an object");
+    const live = {};
+    const phone = str(body.phone);
+    if (phone?.startsWith("+"))
+        live.phone = phone;
+    const whatsapp = str(body.whatsapp);
+    if (whatsapp?.startsWith("+"))
+        live.whatsapp = whatsapp;
+    if (isObject(body.address)) {
+        const street = str(body.address.street);
+        const postalCode = str(body.address.postalCode);
+        const locality = str(body.address.locality);
+        if (street && postalCode && /^\d{5}$/.test(postalCode) && locality)
+            live.address = { street, postalCode, locality };
+    }
+    if (isObject(body.geo)) {
+        const lat = num(body.geo.lat);
+        const lng = num(body.geo.lng);
+        if (lat !== undefined && lng !== undefined)
+            live.geo = { lat, lng };
+    }
+    const h = hours(body.hours);
+    if (h && h.length > 0)
+        live.hours = h;
+    const photo = httpsUrl(body.storefrontPhoto);
+    if (photo)
+        live.storefrontPhoto = photo;
+    const mark = landmark(body.landmark, locales);
+    if (mark)
+        live.landmark = mark;
+    if (Array.isArray(body.serviceArea)) {
+        const names = body.serviceArea.map(str).filter((a) => a !== undefined);
+        if (names.length > 0)
+            live.serviceArea = [{ kind: "localities", names }];
+    }
+    const r = rating(body.rating);
+    if (r)
+        live.rating = r;
+    return live;
+}
+/**
+ * The live fields over the baked ones. A service-area place takes none of the
+ * storefront's: an address, a pin or a photo from the source would give it a
+ * front it does not have.
+ */
+export function mergeLive(baked, live) {
+    const front = baked.presence;
+    return {
+        ...baked,
+        presence: front.kind === "storefront"
+            ? {
+                ...front,
+                address: live.address ? { ...front.address, ...live.address } : front.address,
+                geo: live.geo ?? front.geo,
+                storefrontPhoto: live.storefrontPhoto ?? front.storefrontPhoto,
+                landmark: live.landmark ?? front.landmark,
+            }
+            : front,
+        channels: { phone: live.phone ?? baked.channels.phone, whatsapp: live.whatsapp ?? baked.channels.whatsapp },
+        serviceArea: live.serviceArea ?? baked.serviceArea,
+        hours: live.hours ?? baked.hours,
+        rating: live.rating ?? baked.rating,
+    };
+}

package/dist/core/place/publication.d.ts

@@ -0,0 +1,29 @@
+import type { Place } from "./types.js";
+/**
+ * The fields that make a place's page about *that* place. Google's spam policy
+ * names "many similar pages that funnel to one business" as doorway pages, and
+ * a network of pages that differ only by address is exactly that. So a place
+ * is indexable only once it says something its neighbours cannot.
+ */
+export type PublicationField = "storefrontPhoto" | "landmark" | "serviceArea" | "hours";
+/** Which fields a place must fill before it may be indexed. */
+export interface PublicationPolicy {
+    required(place: Place<string>): readonly PublicationField[];
+}
+/**
+ * A storefront network: what the place looks like, how to find it, where its
+ * van goes, and when it opens.
+ */
+export declare const STOREFRONT_GATE: PublicationPolicy;
+/** A service-area business has no front to photograph: its zone and its hours. */
+export declare const SERVICE_AREA_GATE: PublicationPolicy;
+/** What is still missing, in the policy's order; empty means the place may be indexed. */
+export declare function publicationGaps(place: Place<string>, policy: PublicationPolicy): PublicationField[];
+/**
+ * An unpublished place still answers — its phone is real and someone may have
+ * been given the link — but it carries `noindex` and stays out of the sitemap.
+ * A site with no domain yet publishes nothing.
+ */
+export declare function isPublished(place: Place<string>, policy: PublicationPolicy, site: {
+    domain: string | null;
+}): boolean;

package/dist/core/place/publication.js

@@ -0,0 +1,42 @@
+/**
+ * A storefront network: what the place looks like, how to find it, where its
+ * van goes, and when it opens.
+ */
+export const STOREFRONT_GATE = {
+    required: () => ["storefrontPhoto", "landmark", "serviceArea", "hours"],
+};
+/** A service-area business has no front to photograph: its zone and its hours. */
+export const SERVICE_AREA_GATE = {
+    required: () => ["serviceArea", "hours"],
+};
+function filled(place, field) {
+    const front = place.presence.kind === "storefront" ? place.presence : null;
+    switch (field) {
+        case "storefrontPhoto":
+            return Boolean(front?.storefrontPhoto);
+        case "landmark": {
+            // In every language the place is named in — an empty `{}` says nothing.
+            const landmark = front?.landmark ?? null;
+            if (!landmark)
+                return false;
+            const locales = Object.keys(place.name);
+            return locales.length > 0 && locales.every(l => (landmark[l] ?? "").trim() !== "");
+        }
+        case "serviceArea":
+            return place.serviceArea !== null && place.serviceArea.length > 0;
+        case "hours":
+            return place.hours !== null && place.hours.length > 0;
+    }
+}
+/** What is still missing, in the policy's order; empty means the place may be indexed. */
+export function publicationGaps(place, policy) {
+    return policy.required(place).filter(field => !filled(place, field));
+}
+/**
+ * An unpublished place still answers — its phone is real and someone may have
+ * been given the link — but it carries `noindex` and stays out of the sitemap.
+ * A site with no domain yet publishes nothing.
+ */
+export function isPublished(place, policy, site) {
+    return site.domain !== null && publicationGaps(place, policy).length === 0;
+}

package/dist/core/place/rating.d.ts

@@ -0,0 +1,16 @@
+import type { Place, Rating } from "./types.js";
+/** Google Business Profile API policy: no cached copy older than this. */
+export declare const RATING_MAX_AGE_DAYS = 30;
+/**
+ * An instant from the live source: RFC 3339 with an offset or `Z`, or a bare
+ * date (midnight UTC). A date-time without an offset is refused — `Date.parse`
+ * would read it in the server's own zone, so one timestamp would mean two
+ * instants on two pods (and in the Rust port). `null` for anything else.
+ */
+export declare function parseInstant(value: string): number | null;
+/**
+ * The rating, only while it may still be shown. A stale or future-dated copy
+ * is treated as absent — the page then says nothing about a rating rather than
+ * something the terms no longer allow.
+ */
+export declare function freshRating(place: Place<string>, now: Date): Rating | null;

package/dist/core/place/rating.js

@@ -0,0 +1,33 @@
+/** Google Business Profile API policy: no cached copy older than this. */
+export const RATING_MAX_AGE_DAYS = 30;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
+/**
+ * An instant from the live source: RFC 3339 with an offset or `Z`, or a bare
+ * date (midnight UTC). A date-time without an offset is refused — `Date.parse`
+ * would read it in the server's own zone, so one timestamp would mean two
+ * instants on two pods (and in the Rust port). `null` for anything else.
+ */
+export function parseInstant(value) {
+    if (!DATE.test(value) && !DATE_TIME.test(value))
+        return null;
+    const t = Date.parse(value);
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * The rating, only while it may still be shown. A stale or future-dated copy
+ * is treated as absent — the page then says nothing about a rating rather than
+ * something the terms no longer allow.
+ */
+export function freshRating(place, now) {
+    const rating = place.rating;
+    if (!rating)
+        return null;
+    const fetched = parseInstant(rating.fetchedAt);
+    if (fetched === null)
+        return null;
+    const age = now.getTime() - fetched;
+    if (age < 0 || age > RATING_MAX_AGE_DAYS * 86_400_000)
+        return null;
+    return rating;
+}