@we8/astro 0.1.0

package/README.md

@@ -0,0 +1,157 @@
+# @we8/astro
+
+The Astro integration for we8. It wraps [`@we8/client`](https://www.npmjs.com/package/@we8/client) (itself a
+thin layer over the OpenAPI-documented `/v1` API) with the pieces an Astro site
+needs: build-time content fetching, a code-first SEO merge, sitemap merging, a
+consent-gated visit beacon, and a progressive-enhancement form. The API is the
+product; this package is the ergonomic way to build a site on it.
+
+## Requirements
+
+- Astro 7 or newer in the consuming site (declared as an optional peer: the
+  helpers run without Astro, the `.astro` components need it).
+- Node 22.12 or newer, which is Astro 7's own floor.
+- `@we8/client` comes with this package as a regular dependency; npm installs
+  it for you.
+- A we8 CMS URL and a publishable key (`WE8_API_URL`, `WE8_PUBLISHABLE_KEY`).
+  Both absent is fine: `tryResolveConfig` returns `null` so a site can fall
+  back to its own data source.
+## Install
+
+```sh
+npm install @we8/astro astro
+```
+
+`astro` is an optional peer dependency: the helpers typecheck and run without
+it, and the `.astro` components need it in the consuming project (which an Astro
+site already has).
+
+## Quick start
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { we8 } from '@we8/astro';
+
+export default defineConfig({
+  site: process.env.SITE, // your public origin, for canonical URLs and sitemap
+  integrations: [we8()], // warns at build start when the env is unset
+});
+```
+
+```astro
+---
+// Any page or layout frontmatter (runs in Node during `astro build`).
+import { getPosts, getSiteConfig, mergeSeo, postUrl } from '@we8/astro';
+
+const site = await getSiteConfig();
+const { items } = await getPosts({ page: 1, pageSize: 10 });
+const seo = mergeSeo({ title: 'Blog' }, site); // page values win, site fills gaps
+---
+<title>{seo.title}</title>
+{items.map((post) => <a href={postUrl(post, site)}>{post.title}</a>)}
+```
+
+## What you get
+
+- Config: `resolveConfig(env?)` (throws when unconfigured),
+  `tryResolveConfig(env?)` (returns `null` instead, for a template that falls
+  back to its own data source), `createBuildClient(config?, fetch?)`.
+- Build-time content: `getPosts`, `getPost`, `getPostSlugs`, `getSiteConfig`,
+  `getDocument` (design.md, llms.txt). These run in Node during `astro build`
+  and need `WE8_API_URL`.
+- SEO: `mergeSeo(page, site)` (code-first merge), `postUrl(post, site)`,
+  `robotsTxt(site, { sitemapUrl? })`.
+- Sitemap: `we8SitemapUrl()` and `mergeSitemap({ map })` to feed
+  `@astrojs/sitemap`'s `customPages` with your post URLs.
+- Consent: `readConsent`, `writeConsent`, `recordConsent(client, choice)`,
+  `analyticsAllowed`, `onAnalyticsConsent(handler)`, plus `CONSENT_STORAGE_KEY`
+  and `CONSENT_EVENT`.
+- Browser: `getSessionId()`, `sendVisit(client)`, `trackVisit(client)` (the
+  consent-gated beacon), `enhanceForm(form, client, opts)`.
+- Re-exports `createClient`, `We8ApiError`, `isWe8ApiError` and the key types
+  from `@we8/client`, so a template needs only this one dependency.
+
+## Components
+
+Import the ready-made components by subpath. Each takes the publishable key as a
+prop and falls back to `PUBLIC_WE8_PUBLISHABLE_KEY`; each degrades rather than
+crashes when no key is available.
+
+```astro
+---
+import ConsentBanner from '@we8/astro/ConsentBanner.astro';
+import VisitBeacon from '@we8/astro/VisitBeacon.astro';
+import We8Form from '@we8/astro/We8Form.astro';
+
+const key = import.meta.env.WE8_PUBLISHABLE_KEY;
+const apiUrl = import.meta.env.WE8_API_URL;
+---
+<ConsentBanner key={key} apiUrl={apiUrl} />
+<VisitBeacon key={key} apiUrl={apiUrl} />
+
+<We8Form formKey="contact" key={key} apiUrl={apiUrl}>
+  <input name="email" type="email" required />
+  <textarea name="body"></textarea>
+  <button type="submit">Send</button>
+</We8Form>
+```
+
+`<We8Form>` progressively enhances a native `<form>`: it POSTs through the
+client and lifts a Cloudflare Turnstile `cf-turnstile-response` field
+automatically. Without a key it stays inert and says so, instead of failing
+silently.
+
+`<ConsentBanner>` ships markup only, no styling: three named decisions, a slot
+for your copy, and a `data-we8-consent-*` hook on every element. It stays hidden
+for a visitor who has already answered.
+
+`<VisitBeacon>` waits for analytics consent by default. The banner's write
+dispatches `we8:consent` and the beacon fires on that event, with no page
+reload. Pass `requireConsent={false}` only if measuring before consent is lawful
+where your visitors are.
+
+## Consent, end to end
+
+```ts
+import { recordConsent, readConsent, createClient } from '@we8/astro';
+
+const client = createClient({ key, baseUrl: apiUrl });
+if (readConsent() === null) showBanner();
+
+// On "Accept all":
+await recordConsent(client, { decision: 'accepted', analytics: true, performance: true });
+```
+
+`recordConsent` persists the decision locally FIRST, announces it, and only then
+reports it to the API. It never rejects: a failed report leaves the visitor's
+choice fully in effect.
+
+## Environment contract
+
+Two variables, both safe to expose:
+
+- `WE8_API_URL`: the absolute API base. For a self-hosted we8 CMS that is its
+  origin with no path on the end, for example `https://cms.example.com`, or
+  `http://localhost:8787` in development. The CMS serves `/v1` at its own root,
+  so a trailing `/api` produces 404s.
+- `WE8_PUBLISHABLE_KEY`: the publishable (`pk_`) key.
+
+Astro only puts `PUBLIC_`-prefixed variables on `import.meta.env` by default. The
+starter template widens `envPrefix` to accept `WE8_` as well, so one variable
+serves both build-time fetches and the browser. If you would rather not, set
+`PUBLIC_WE8_PUBLISHABLE_KEY` and let the components pick it up.
+
+`SITE` is Astro's own `site` config (your public origin). It drives Astro's
+canonical URLs and `@astrojs/sitemap`; it is distinct from the we8 site config's
+`siteUrl` that `postUrl` reads.
+
+A secret (`sk_`) key can be handed to `createBuildClient` directly for a
+server-only build. Never let one reach the browser.
+
+## The contract
+
+The full, authoritative interface is the OpenAPI document your CMS serves at
+`/v1/openapi.json`, keyless, and [the API doc](https://github.com/reveriext/we8-package/blob/main/docs/api.md) is the same
+contract in prose. See [the frontend doc](https://github.com/reveriext/we8-package/blob/main/docs/frontend.md) for how this
+package and the starter template fit together.

package/components/ConsentBanner.astro

@@ -0,0 +1,105 @@
+---
+/**
+ * <ConsentBanner /> - ask for analytics consent, record the answer, and get out
+ * of the way.
+ *
+ * The banner is hidden until the script confirms the visitor has NOT decided
+ * yet, so a returning visitor never sees a flash of it. Choosing writes the
+ * decision locally first, dispatches `we8:consent` (which releases anything
+ * gated on consent, such as <VisitBeacon />), and then reports the decision to
+ * the analytics API. A failed report never undoes the choice.
+ *
+ * Markup only, no styling: three named slots carry your copy, and every element
+ * has a `data-we8-consent-*` hook to style from your own stylesheet. Renders
+ * nothing without a key, so a build with no backend has no dead banner.
+ *
+ * The three decisions map to the API's vocabulary: `accepted` (analytics and
+ * performance), `partial` (analytics only), `declined` (neither).
+ */
+interface Props {
+  /** The publishable key. Defaults to `PUBLIC_WE8_PUBLISHABLE_KEY`. */
+  key?: string | undefined;
+  /** Absolute API base. Defaults to same-origin `/api`. */
+  apiUrl?: string | undefined;
+  acceptLabel?: string;
+  essentialLabel?: string;
+  declineLabel?: string;
+  /** Accessible name for the region. */
+  label?: string;
+}
+
+const {
+  key = import.meta.env.PUBLIC_WE8_PUBLISHABLE_KEY,
+  apiUrl,
+  acceptLabel = 'Accept analytics',
+  essentialLabel = 'Analytics only',
+  declineLabel = 'Decline',
+  label = 'Cookie choices',
+} = Astro.props;
+---
+
+{
+  key && (
+    <div
+      data-we8-consent
+      data-we8-key={key}
+      data-we8-api={apiUrl ?? ''}
+      role="region"
+      aria-label={label}
+      hidden
+    >
+      <div data-we8-consent-body>
+        <slot>
+          <p>
+            We count page views to see which pages are useful. Nothing is sold, and no
+            profile is built. You can decline and the site works exactly the same.
+          </p>
+        </slot>
+      </div>
+      <div data-we8-consent-actions>
+        <button type="button" data-we8-consent-choice="accepted">
+          {acceptLabel}
+        </button>
+        <button type="button" data-we8-consent-choice="partial">
+          {essentialLabel}
+        </button>
+        <button type="button" data-we8-consent-choice="declined">
+          {declineLabel}
+        </button>
+      </div>
+    </div>
+  )
+}
+
+<script>
+  import { createClient } from '@we8/client';
+  import { readConsent, recordConsent } from '@we8/astro';
+
+  const banner = document.querySelector<HTMLElement>('[data-we8-consent]');
+  const key = banner?.dataset.we8Key;
+  if (banner && key && !banner.dataset.we8Bound) {
+    banner.dataset.we8Bound = 'true';
+
+    // Only ask visitors who have not answered. A stored decision of any kind,
+    // including a decline, is an answer.
+    if (readConsent() === null) {
+      banner.hidden = false;
+      const apiUrl = banner.dataset.we8Api;
+      const client = createClient(apiUrl ? { key, baseUrl: apiUrl } : { key });
+
+      for (const el of banner.querySelectorAll('[data-we8-consent-choice]')) {
+        el.addEventListener('click', () => {
+          const choice = (el as HTMLElement).dataset.we8ConsentChoice;
+          const decision =
+            choice === 'accepted' ? 'accepted' : choice === 'partial' ? 'partial' : 'declined';
+          banner.hidden = true;
+          void recordConsent(client, {
+            decision,
+            analytics: decision !== 'declined',
+            performance: decision === 'accepted',
+          });
+        });
+      }
+    }
+  }
+</script>

package/components/VisitBeacon.astro

@@ -0,0 +1,58 @@
+---
+/**
+ * <VisitBeacon /> - fire a single page-visit beacon after the page loads.
+ *
+ * The key is a publishable (`pk_`) key, safe to embed in a shipped frontend by
+ * design. Pass it explicitly from your own config (recommended, and what the
+ * starter template does) or let it fall back to `PUBLIC_WE8_PUBLISHABLE_KEY`,
+ * which Astro exposes to the browser. It travels to the script through a data
+ * attribute, so no build-time env plumbing is needed in the consuming project.
+ *
+ * By default the beacon waits for analytics consent (see <ConsentBanner> in the
+ * starter, or `recordConsent` from this package). Set `requireConsent={false}`
+ * only if your jurisdiction and your privacy policy allow measuring first.
+ *
+ * Renders nothing when no key is available, so a misconfigured build degrades
+ * to "no analytics" rather than a runtime error.
+ */
+interface Props {
+  /** The publishable key. Defaults to `PUBLIC_WE8_PUBLISHABLE_KEY`. */
+  key?: string | undefined;
+  /** Absolute API base. Defaults to same-origin `/api`. */
+  apiUrl?: string | undefined;
+  /** Wait for analytics consent before sending. Default true. */
+  requireConsent?: boolean;
+}
+
+const {
+  key = import.meta.env.PUBLIC_WE8_PUBLISHABLE_KEY,
+  apiUrl,
+  requireConsent = true,
+} = Astro.props;
+---
+
+{
+  key && (
+    <span
+      data-we8-beacon
+      data-we8-key={key}
+      data-we8-api={apiUrl ?? ''}
+      data-we8-require-consent={requireConsent ? 'true' : 'false'}
+      hidden
+    />
+  )
+}
+
+<script>
+  import { createClient } from '@we8/client';
+  import { trackVisit } from '@we8/astro';
+
+  const el = document.querySelector<HTMLElement>('[data-we8-beacon]');
+  const key = el?.dataset.we8Key;
+  if (el && key && !el.dataset.we8Bound) {
+    el.dataset.we8Bound = 'true';
+    const apiUrl = el.dataset.we8Api;
+    const client = createClient(apiUrl ? { key, baseUrl: apiUrl } : { key });
+    trackVisit(client, { requireConsent: el.dataset.we8RequireConsent !== 'false' });
+  }
+</script>

package/components/We8Form.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * <We8Form formKey="contact"> ... form fields ... </We8Form>
+ *
+ * A progressively-enhanced form. The child fields go in the default slot; on
+ * submit, the JS handler POSTs them through the we8 client to
+ * `/v1/forms/{formKey}/submissions` and shows a status line. A Cloudflare
+ * Turnstile widget's `cf-turnstile-response` field is lifted automatically.
+ *
+ * The submission endpoint takes JSON, so JS is required to submit; without it
+ * the markup is still a valid, accessible form (put a mailto or other fallback
+ * in the slot if a no-JS path matters).
+ *
+ * The key is a publishable (`pk_`) key. Pass it explicitly from your own config
+ * (what the starter template does) or let it fall back to
+ * `PUBLIC_WE8_PUBLISHABLE_KEY`. With no key at all the form still renders and
+ * simply reports that submissions are not configured, so a fixtures-only build
+ * shows the real markup instead of crashing.
+ */
+interface Props {
+  formKey: string;
+  /** The publishable key. Defaults to `PUBLIC_WE8_PUBLISHABLE_KEY`. */
+  key?: string | undefined;
+  /** Absolute API base. Defaults to same-origin `/api`. */
+  apiUrl?: string | undefined;
+  class?: string | undefined;
+  successMessage?: string;
+  errorMessage?: string;
+  offlineMessage?: string;
+}
+
+const {
+  formKey,
+  key = import.meta.env.PUBLIC_WE8_PUBLISHABLE_KEY,
+  apiUrl,
+  class: className,
+  successMessage = 'Thanks. Your message is on its way.',
+  errorMessage = 'Something went wrong. Please try again.',
+  offlineMessage = 'This form is not connected to a backend yet.',
+} = Astro.props;
+---
+
+<form
+  class={className}
+  data-we8-form-key={formKey}
+  data-we8-key={key ?? ''}
+  data-we8-api={apiUrl ?? ''}
+  data-we8-success={successMessage}
+  data-we8-error={errorMessage}
+  data-we8-offline={offlineMessage}
+>
+  <slot />
+  <p data-we8-status role="status" aria-live="polite" hidden></p>
+</form>
+
+<script>
+  import { createClient } from '@we8/client';
+  import { enhanceForm } from '@we8/astro';
+
+  for (const el of document.querySelectorAll('form[data-we8-form-key]')) {
+    const form = el as HTMLFormElement;
+    // Guard against binding the same form twice if this module ever runs again.
+    if (form.dataset.we8Bound) continue;
+    form.dataset.we8Bound = 'true';
+
+    const formKey = form.dataset.we8FormKey;
+    if (!formKey) continue;
+
+    const status = form.querySelector('[data-we8-status]') as HTMLElement | null;
+    const show = (message: string) => {
+      if (!status) return;
+      status.hidden = false;
+      status.textContent = message;
+    };
+
+    const key = form.dataset.we8Key;
+    if (!key) {
+      // No key: keep the form inert but honest rather than silently dead.
+      form.addEventListener('submit', (event) => {
+        event.preventDefault();
+        show(form.dataset.we8Offline ?? 'This form is not connected to a backend yet.');
+      });
+      continue;
+    }
+
+    const apiUrl = form.dataset.we8Api;
+    const client = createClient(apiUrl ? { key, baseUrl: apiUrl } : { key });
+    enhanceForm(form, client, {
+      formKey,
+      onSuccess: () => show(form.dataset.we8Success ?? 'Thanks.'),
+      onError: () => show(form.dataset.we8Error ?? 'Something went wrong.'),
+    });
+  }
+</script>

package/dist/beacon.d.ts

@@ -0,0 +1,32 @@
+import type { We8Client } from '@we8/client';
+import { type EventTargetLike } from './consent.js';
+import { type StorageLike } from './session.js';
+export interface BeaconOptions {
+    /** Defaults to `location.pathname`. */
+    pathname?: string;
+    /** Defaults to `document.referrer`. */
+    referrer?: string;
+}
+/**
+ * Send a page-visit beacon for the current page, tagged with the persisted
+ * session id. Errors are swallowed: analytics must never break the page it
+ * measures.
+ */
+export declare function sendVisit(client: We8Client, options?: BeaconOptions): Promise<void>;
+export interface TrackVisitOptions extends BeaconOptions {
+    /**
+     * Hold the beacon until the visitor has granted analytics consent. Default
+     * `true`: measuring before consent is the thing a consent banner exists to
+     * prevent, so opting out of the gate has to be deliberate.
+     */
+    requireConsent?: boolean;
+    storage?: StorageLike | null;
+    target?: EventTargetLike | null;
+}
+/**
+ * Send the visit beacon, gated on analytics consent: now if consent already
+ * exists, otherwise the moment the visitor grants it. Returns a cleanup
+ * function that cancels a still-waiting beacon.
+ */
+export declare function trackVisit(client: We8Client, options?: TrackVisitOptions): () => void;
+//# sourceMappingURL=beacon.d.ts.map

package/dist/beacon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.d.ts","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAa7F;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,IAAI,CAUzF"}

package/dist/beacon.js

@@ -0,0 +1,38 @@
+import { onAnalyticsConsent } from './consent.js';
+import { getSessionId } from './session.js';
+/**
+ * Send a page-visit beacon for the current page, tagged with the persisted
+ * session id. Errors are swallowed: analytics must never break the page it
+ * measures.
+ */
+export async function sendVisit(client, options = {}) {
+    try {
+        const pathname = options.pathname ?? (typeof location !== 'undefined' ? location.pathname : '/');
+        const referrer = options.referrer ?? (typeof document !== 'undefined' ? document.referrer : '');
+        await client.events.visit({
+            pathname,
+            sessionId: getSessionId(),
+            ...(referrer ? { referrer } : {}),
+        });
+    }
+    catch {
+        // Intentionally silent: a dropped beacon is invisible to the visitor.
+    }
+}
+/**
+ * Send the visit beacon, gated on analytics consent: now if consent already
+ * exists, otherwise the moment the visitor grants it. Returns a cleanup
+ * function that cancels a still-waiting beacon.
+ */
+export function trackVisit(client, options = {}) {
+    const { requireConsent = true, storage, target, ...beacon } = options;
+    if (!requireConsent) {
+        void sendVisit(client, beacon);
+        return () => undefined;
+    }
+    return onAnalyticsConsent(() => void sendVisit(client, beacon), {
+        ...(storage === undefined ? {} : { storage }),
+        ...(target === undefined ? {} : { target }),
+    });
+}
+//# sourceMappingURL=beacon.js.map

package/dist/beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"beacon.js","sourceRoot":"","sources":["../src/beacon.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAwB,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,YAAY,EAAoB,MAAM,cAAc,CAAC;AAS9D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAiB,EAAE,UAAyB,EAAE;IAC5E,IAAI,CAAC;QACH,MAAM,QAAQ,GACZ,OAAO,CAAC,QAAQ,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAClF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAChG,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;YACxB,QAAQ;YACR,SAAS,EAAE,YAAY,EAAE;YACzB,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;AACH,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAiB,EAAE,UAA6B,EAAE;IAC3E,MAAM,EAAE,cAAc,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IACtE,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,KAAK,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IACzB,CAAC;IACD,OAAO,kBAAkB,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;QAC9D,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;QAC7C,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5C,CAAC,CAAC;AACL,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,42 @@
+import { type We8Client } from '@we8/client';
+export interface We8AstroConfig {
+    /**
+     * The site API key. Use a publishable key (`pk_...`) for anything that ends
+     * up in the browser (the beacon, the consent banner, the form); a secret key
+     * (`sk_...`) is only for build-time server fetches and must never be shipped
+     * to a client.
+     */
+    key: string;
+    /**
+     * Absolute API base URL for build-time (Node) fetches. For a self-hosted
+     * we8 CMS that is its origin with no path on the end, for example
+     * `https://cms.example.com`, since the CMS serves `/v1` at its own root.
+     * Required by `getPosts`/`getPost`, which run during `astro build` where
+     * there is no same-origin to default to.
+     */
+    apiUrl?: string;
+}
+export type EnvLike = Record<string, string | undefined>;
+/** The environment variable holding the publishable key. */
+export declare const KEY_ENV = "WE8_PUBLISHABLE_KEY";
+/** The environment variable holding the absolute API base URL. */
+export declare const API_URL_ENV = "WE8_API_URL";
+/**
+ * Resolve the we8 config from an env record (defaults to `process.env`).
+ * `WE8_PUBLISHABLE_KEY` is required; `WE8_API_URL` is optional here and only
+ * needed for build-time content fetches, which check it themselves.
+ */
+export declare function resolveConfig(env?: EnvLike): We8AstroConfig;
+/**
+ * Like `resolveConfig`, but returns `null` instead of throwing when the
+ * environment is not configured. A template uses this to fall back to its own
+ * data source (fixtures, a different backend) rather than failing the build.
+ */
+export declare function tryResolveConfig(env?: EnvLike): We8AstroConfig | null;
+/**
+ * Build a `@we8/client` for BUILD-TIME (Node) use. Unlike the browser default
+ * (same-origin `/api`), this needs an absolute `apiUrl`, since `astro build`
+ * runs off-origin. Pass `fetchImpl` in tests.
+ */
+export declare function createBuildClient(config?: We8AstroConfig, fetchImpl?: typeof fetch): We8Client;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,OAAO,wBAAwB,CAAC;AAC7C,kEAAkE;AAClE,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAYzC;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,OAA0B,GAAG,cAAc,CAW7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,OAA0B,GAAG,cAAc,GAAG,IAAI,CAKvF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,cAAgC,EACxC,SAAS,CAAC,EAAE,OAAO,KAAK,GACvB,SAAS,CAYX"}

package/dist/config.js

@@ -0,0 +1,58 @@
+import { createClient } from '@we8/client';
+/** The environment variable holding the publishable key. */
+export const KEY_ENV = 'WE8_PUBLISHABLE_KEY';
+/** The environment variable holding the absolute API base URL. */
+export const API_URL_ENV = 'WE8_API_URL';
+/**
+ * Read the default env record without depending on `@types/node`: reach for a
+ * `process.env` on `globalThis` if the runtime has one (Node during `astro
+ * build`), otherwise an empty record.
+ */
+function readDefaultEnv() {
+    const g = globalThis;
+    return g.process?.env ?? {};
+}
+/**
+ * Resolve the we8 config from an env record (defaults to `process.env`).
+ * `WE8_PUBLISHABLE_KEY` is required; `WE8_API_URL` is optional here and only
+ * needed for build-time content fetches, which check it themselves.
+ */
+export function resolveConfig(env = readDefaultEnv()) {
+    const key = env[KEY_ENV];
+    if (!key) {
+        throw new Error(`@we8/astro: ${KEY_ENV} is not set. Add your site's publishable key to the environment (for example in .env).`);
+    }
+    const apiUrl = env[API_URL_ENV];
+    // Build the object with the optional field present only when set, to stay
+    // clean under exactOptionalPropertyTypes.
+    return apiUrl ? { key, apiUrl } : { key };
+}
+/**
+ * Like `resolveConfig`, but returns `null` instead of throwing when the
+ * environment is not configured. A template uses this to fall back to its own
+ * data source (fixtures, a different backend) rather than failing the build.
+ */
+export function tryResolveConfig(env = readDefaultEnv()) {
+    const key = env[KEY_ENV];
+    const apiUrl = env[API_URL_ENV];
+    if (!key || !apiUrl)
+        return null;
+    return { key, apiUrl };
+}
+/**
+ * Build a `@we8/client` for BUILD-TIME (Node) use. Unlike the browser default
+ * (same-origin `/api`), this needs an absolute `apiUrl`, since `astro build`
+ * runs off-origin. Pass `fetchImpl` in tests.
+ */
+export function createBuildClient(config = resolveConfig(), fetchImpl) {
+    if (!config.apiUrl) {
+        throw new Error(`@we8/astro: ${API_URL_ENV} is required for build-time fetch (getPosts/getPost). ` +
+            'Set it to your CMS origin, for example https://cms.example.com.');
+    }
+    return createClient({
+        key: config.key,
+        baseUrl: config.apiUrl,
+        ...(fetchImpl ? { fetch: fetchImpl } : {}),
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAkB,MAAM,aAAa,CAAC;AAsB3D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAC7C,kEAAkE;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,aAAa,CAAC;AAEzC;;;;GAIG;AACH,SAAS,cAAc;IACrB,MAAM,CAAC,GAAG,UAA6C,CAAC;IACxD,OAAO,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAe,cAAc,EAAE;IAC3D,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,eAAe,OAAO,wFAAwF,CAC/G,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;IAChC,0EAA0E;IAC1E,0CAA0C;IAC1C,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAe,cAAc,EAAE;IAC9D,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IACzB,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAyB,aAAa,EAAE,EACxC,SAAwB;IAExB,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,eAAe,WAAW,wDAAwD;YAChF,iEAAiE,CACpE,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC;QAClB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,OAAO,EAAE,MAAM,CAAC,MAAM;QACtB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC,CAAC;AACL,CAAC"}

package/dist/consent.d.ts

@@ -0,0 +1,61 @@
+import type { ConsentDecision, We8Client } from '@we8/client';
+import type { StorageLike } from './session.js';
+/** Where a visitor's consent decision is persisted in the browser. */
+export declare const CONSENT_STORAGE_KEY = "we8:consent";
+/**
+ * The DOM event dispatched (and listened for) when a decision is recorded, so
+ * anything gated on consent (the visit beacon, an embedded map, a third-party
+ * script) can start the moment the visitor says yes, without a page reload.
+ */
+export declare const CONSENT_EVENT = "we8:consent";
+/** A visitor's stored consent decision. */
+export interface ConsentState {
+    decision: ConsentDecision;
+    analytics: boolean;
+    performance: boolean;
+    /** ISO timestamp of when the visitor decided. */
+    decidedAt: string;
+}
+/** The minimal event-target surface `recordConsent` and `onConsent` need; `window` satisfies it. */
+export interface EventTargetLike {
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+    dispatchEvent?(event: Event): boolean;
+}
+/**
+ * Read the stored decision, or `null` when the visitor has not chosen yet (so
+ * a banner knows to show itself). A corrupt or unreadable store also reads as
+ * `null`: an unparseable decision is not a decision.
+ */
+export declare function readConsent(storage?: StorageLike | null): ConsentState | null;
+/** True when the visitor has granted analytics consent. Convenience for gating a beacon. */
+export declare function analyticsAllowed(storage?: StorageLike | null): boolean;
+/** Persist a decision locally and announce it. Storage failures are non-fatal. */
+export declare function writeConsent(state: ConsentState, storage?: StorageLike | null, target?: EventTargetLike | null): void;
+export interface RecordConsentOptions {
+    storage?: StorageLike | null;
+    target?: EventTargetLike | null;
+    /** Override the session id (defaults to the persisted visitor session id). */
+    sessionId?: string;
+}
+/**
+ * Record a visitor's consent decision: persist it locally FIRST (so the
+ * decision is honored even if the network is down), announce it, then report
+ * it to the analytics API. Never rejects; a failed report is invisible to the
+ * visitor and does not weaken the decision.
+ */
+export declare function recordConsent(client: We8Client, choice: {
+    decision: ConsentDecision;
+    analytics: boolean;
+    performance: boolean;
+}, options?: RecordConsentOptions): Promise<ConsentState>;
+/**
+ * Run `handler` once analytics consent exists: immediately if it already does,
+ * otherwise on the next consent decision that grants it. Returns a cleanup
+ * function that detaches the listener.
+ */
+export declare function onAnalyticsConsent(handler: () => void, options?: {
+    storage?: StorageLike | null;
+    target?: EventTargetLike | null;
+}): () => void;
+//# sourceMappingURL=consent.d.ts.map

package/dist/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../src/consent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAE3C,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oGAAoG;AACpG,MAAM,WAAW,eAAe;IAC9B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC9D,aAAa,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;CACvC;AAmBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,GAAE,WAAW,GAAG,IAAuB,GAAG,YAAY,GAAG,IAAI,CAqB/F;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,WAAW,GAAG,IAAuB,GAAG,OAAO,CAExF;AAED,kFAAkF;AAClF,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,WAAW,GAAG,IAAuB,EAC9C,MAAM,GAAE,eAAe,GAAG,IAAsB,GAC/C,IAAI,CAYN;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,EAC/E,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,YAAY,CAAC,CAkBvB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,IAAI,EACnB,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;CAAO,GAC9E,MAAM,IAAI,CAgBZ"}