@pikku/core 0.12.107 → 0.12.112

package/CHANGELOG.md

@@ -1,3 +1,360 @@
+## 0.12.112
+
+### Patch Changes
+
+- 02eeffb: fix: hot reload reads the changed source instead of a leftover compiled copy
+
+  `pikku dev` announced `Hot-reloaded: <fn>` and kept serving the previous
+  implementation whenever a `.js` from an earlier `tsc`, `pikku dist` or bundler
+  run sat beside the edited `.ts` — the reloader preferred that file, and dev
+  never rebuilds it. The changed source is now what runs, and the module runner
+  resolves and compiles the project's own TypeScript dependencies so a helper
+  edited alongside its caller reloads with it.
+
+## 0.12.111
+
+### Patch Changes
+
+- 78237ac: The console shows feature flags as a launch board, and analytics events as a
+  declared catalog.
+
+  A flag's state is four fields — `enabled`, `rolloutPercent`, `declared`,
+  `backed` — and none of them is the question an operator actually asks, which is
+  how far this has got. The board answers that directly: every declared flag sits
+  in the lane its rollout has reached, `dark` → `rolling` → `live`, with
+  `attention` for the flags that are not resolving in a way anybody chose.
+
+  Attention is evaluated before every other reading, and that ordering is the
+  whole point rather than an implementation detail. A flag declared in code with
+  no row in the store fails open, and it reports `enabled: true` with no rollout
+  limit — byte-identical to a deliberate full launch. Read the fields in the
+  obvious order and the one production-severity state on the board renders as the
+  healthiest one. `groupFlagsByLane` also returns all four lanes whether or not
+  they hold anything, because a board read by shape must not rearrange itself the
+  moment a lane empties.
+
+  Selecting a flag opens its controls beside the board rather than over it: the
+  switch, the rollout bucket, and the subjects pinned on or off past that bucket.
+  They share one surface because they are read together — "off for everyone except
+  these three" is a switch and an override row, and an operator who has to leave
+  one screen to see the other is the operator who turns a flag on for everybody by
+  mistake. The panel tracks the open flag by name and re-reads it from the list, so
+  committing a rollout moves the card and the panel together instead of leaving the
+  panel describing the flag as it was before the operator changed it.
+
+  A board whose flags come from a `FeatureFlagSource` — a provider Pikku reads but
+  does not own — says so and offers no controls, rather than offering controls that
+  would fail.
+
+  The analytics screen is a catalog of what the code declares, read from build-time
+  meta: the events a client may emit and the props each carries, with every prop
+  rendered as the schema source text the declaration wrote. It is deliberately not
+  a volume report — nothing here counts what was emitted — and saying which of the
+  two it is turned out to be the only design question the screen had.
+
+  Turning a flag on while it carries no rollout limit now asks first. That press
+  is the one irreversible thing the board can do — with no bucket left to hold
+  anybody back it admits everyone the flag's capabilities allow — and it used to
+  be a single click on a switch. The panel also reports what a mutation is doing
+  and what it refused to do: the controls it is waiting on go into a pending
+  state, and a failed write raises an inline `<Alert>` rather than reverting in
+  silence. The console mounts no notification provider, so the feedback is inline
+  where the action is, which is the idiom the rest of the console already uses.
+
+  `@pikku/mantine`'s theme gains four aliases, and they close a contrast defect
+  that predates this board:
+
+  ```ts
+  '--mantine-color-orange-light': 'var(--app-surface-warning)',
+  '--mantine-color-orange-light-color': 'var(--app-amber)',
+  '--mantine-color-teal-light': 'var(--app-surface-success)',
+  '--mantine-color-teal-light-color': 'var(--app-green)',
+  ```
+
+  The theme already documents two colour tiers — TEXT must clear AA, GRAPHIC only
+  3:1 — and already pulls Mantine's own variables into that contract rather than
+  linting call sites. What it had not covered was Mantine's _light variants_:
+  `<Alert color="orange">` renders #d9480f on #ffe8cc at 3.62:1, and
+  `<Badge variant="light" color="teal">` at 4.33:1, neither reachable from an
+  `--app-*` token because the component never asks for one. The ramp itself is
+  deliberately untouched: Mantine conflates `--mantine-color-orange-filled`
+  between `c="orange"` text and a `variant="filled"` background, so darkening it
+  for light-mode text would make an existing filled badge unreadable in dark mode.
+  Eight pre-existing `c="orange"` call sites moved onto the amber TEXT tier in the
+  same pass.
+
+  The analytics catalog is grouped by the file that declares each event, and its
+  rows are real buttons rather than table cells carrying a tabindex.
+
+  `ShellHeaderAction` gains `loading` and `testId`, and `ActionCluster` gains a
+  `measurement` flag. `ShellHeader` sizes its actions by rendering them a second
+  time off-screen, and that measuring copy was carrying the same `data-testid` and
+  `data-help` as the real one — so every action on a page with a collapsing header
+  resolved to two elements. The flags board also moved its two header actions from
+  `actionsNode` (documented as the non-collapsing escape hatch) onto the structured
+  `actions` array, which is what stopped them clipping off the right edge at 400px.
+
+- add56d2: Reading webhook deliveries no longer throws when nothing persists them.
+
+  `WebhookService.listDeliveries` and `getDelivery` return `[]`/`null` instead of `NotImplementedError`, so the console's webhooks page shows an empty list on an app whose service only delivers. `recordAttempt` still throws — a write that goes nowhere loses the caller's data.
+
+## 0.12.110
+
+### Patch Changes
+
+- 1c9a55a: Analytics can fan out to several destinations, and carry the identity an ad
+  platform needs.
+
+  `fanOutAnalytics` composes any number of destinations into one
+  `AnalyticsService`, so a single-destination app never meets it and a sink is the
+  same class whether it runs alone or beside three others. Destinations are
+  settled rather than awaited in sequence: `flush()` runs inside the invocation,
+  so a slow vendor must not add its latency to the request and a vendor that is
+  down must not cost the others their events.
+
+  Each destination takes an optional `accepts` predicate. Which events a
+  destination receives is the app's policy — a product-analytics tool wants
+  everything, an ad platform wants three conversions — while what an event should
+  look like once it arrives is the sink's, and belongs in its mapper rather than
+  in a central mapping table that would push vendor trivia into every app.
+
+  `AnalyticsIdentity` gains `vendorIds` and `consent`. GA4 keys on a `client_id`
+  from the `_ga` cookie and Meta on `fbp`/`fbc`; neither is derivable from a user
+  id, so a server-side sink without them does not degrade, it sends nothing
+  usable. Both are resolved server-side through an `analyticsIdentity` resolver on
+  singleton services, never read from the event body — the same rule the rest of
+  the identity already follows, so a crafted client call cannot attribute an event
+  to someone else. `cookieAnalyticsIdentity` covers the common first-party-cookie
+  case; a consent tool that packs every purpose into one encoded blob writes its
+  own resolver, which is why the resolver is a function.
+
+  A resolver returns nothing off a wire with no browser behind it, so a cron task
+  and a queue worker never invent a vendor id.
+
+  The analytics leaf re-exports the runtime, so an app reaches the whole surface
+  through `#pikku/analytics` — wiring where events go sits next to declaring them,
+  and splitting that across two specifiers splits one concern across two names.
+
+  Identity the browser owns is resolved server-side, and can now be created there
+  too. `cookieAnalyticsIdentity` reads GA4's `client_id` and Meta's `fbp`/`fbc`
+  off first-party cookies; `mintCookie` writes one that is not there yet, which is
+  what lets an app collect nothing on the page at all. Both formats are public and
+  server-side minting is documented by the vendors — it is the mechanism behind
+  server-side tagging, offered here as a wired resolver rather than a second
+  container to operate.
+
+  Minting is gated on consent, because writing the cookie is itself the act
+  consent governs — a minter that runs before the banner is answered has already
+  done the thing the send gate was meant to prevent. `composeAnalyticsIdentity`
+  exists to make that expressible: resolvers run in order and each sees what the
+  ones before it produced, so the reader that finds consent necessarily precedes
+  the minter that needs it. Every required purpose must be granted, not any.
+
+  `anonymousAnalyticsIdentity` fills the gap that made anonymous product analytics
+  dishonest. `pikkuUserId` is derived from a session and so is absent for exactly
+  the visitor it would need to identify, which left a sink choosing between
+  collapsing every anonymous visitor into one shared literal and dropping the
+  pre-signup funnel entirely. The id is `httpOnly` by default: no browser script
+  needs it, and a cookie scripts cannot touch is not subject to the seven-day cap
+  browsers place on script-set ones.
+
+  On the client, `createAnalytics` takes an `enabled` predicate checked at each
+  flush. A boolean would be captured before anyone had answered the banner, so
+  accepting mid-session would never start and withdrawing would never stop.
+  Refused events are discarded rather than held, so changing your mind does not
+  release a backlog.
+
+- 1c9a55a: Review fixes across the feature-flag and analytics primitives:
+
+  - An addon function's `featureFlag:` gate now reads the consuming application's
+    flag source rather than the package's own services, which never carry one.
+  - A flag named `__proto__`, `constructor` or `prototype` is rejected instead of
+    being silently dropped from the generated metadata.
+  - Two declarations of one flag with different descriptions are a hard error,
+    rather than the inspector's traversal order deciding what operators read.
+  - `subjectIdOf` falls through an empty organization id to the user, instead of
+    resolving to no subject and skipping every override and rollout bucket.
+  - `CachedFlagSource.invalidate()` retires the in-flight read, so a webhook that
+    lands mid-fetch is not answered by the pre-webhook snapshot for another TTL.
+  - The generated `/feature-flags` wire resolves against the compiled fallback
+    when no source is wired, so a scope-gated flag is not reported to a caller
+    who cannot hold it.
+  - `pruneFlags()` rechecks `declared = false` in the delete and reports only
+    what it removed, so a redeclaration between the two keeps its overrides.
+  - A destination's `accepts` throwing no longer costs every later sink its batch.
+  - The React analytics client drops events at collection time when analytics is
+    disabled, so a later consent grant cannot send what was gathered before it.
+  - The React flag client keeps its map when the wire answers a non-object.
+  - `KyselyAnalyticsService` mints event ids from `crypto` rather than a
+    timestamp with a short random tail.
+
+- 1c9a55a: Feature flags, declared in source and resolved from two independent booleans.
+
+  `defineFeatureFlags` declares a flag the way `defineScopes` declares a scope —
+  the inspector collects it, the CLI emits a `FeatureFlagName` union, and a
+  misspelled `featureFlag:` is a type error rather than a gate that silently fails
+  open.
+
+  A flag answers two questions that are not the same question. `capable` comes
+  from the session's scopes and is per-user, advisory, and protects nothing — it
+  hides UI. `available` comes from one global config snapshot, is caller-blind,
+  and is the only half the runner enforces: `override(subject) ?? (enabled AND
+bucket)`, so "off for everyone except these three organizations" is one row, and
+  a kill is one write rather than a fan-out. Authorization stays where it was, in
+  the function's own `scopes:` — enforcing capability would make a flag a second
+  authorization path OR-ing against them. An unavailable feature throws 503, not
+  403, because the caller was allowed; the feature was not on.
+
+  `featureFlag:` is deliberately available on sessionless functions too. It reads
+  the config, not the session, so the kill switch reaches a cron task, a queue
+  worker and a webhook — which is where it matters most, since nobody is watching
+  a UI to notice the feature is off.
+
+  Refresh is pull-on-demand, so the TTL is the kill-switch latency. Where that is
+  too long, `invalidate()` is public: a provider's change webhook lands on an HTTP
+  wiring, drops the cache, and the next request does the read. It deliberately
+  does not fetch — a burst of webhooks would be N round trips, and on a serverless
+  runtime the isolate that took the signal may be gone before anything reads the
+  result.
+
+  Availability fails open through three layers: a fresh read, then the last good
+  cached read, then the compiled declaration. The middle layer is load-bearing —
+  dropping straight to the compiled fallback on a blip would switch on every flag
+  that was deliberately dark.
+
+  Backing stores split along what they can honestly do. `FeatureFlagSource` is
+  read-only (`snapshot()`) and is what a third-party provider implements;
+  `FeatureFlagStore` adds the write half and is for stores Pikku owns.
+  `@pikku/kysely` ships the store, with declarations synced additively — a removed
+  declaration is marked undeclared, never revoked, and a sync never re-enables a
+  killed flag. Third-party providers implement the read-only half in the addons
+  repository, over plain `fetch` rather than a vendor SDK — those poll on a timer
+  belonging to a long-lived process, which a serverless isolate cannot hold
+  between requests.
+
+  A client asks for its flags once per session rather than per flag:
+  `scaffold.featureFlags` generates a `GET /feature-flags` returning every
+  declared flag resolved for the caller, keyed by this app's `FeatureFlagName`.
+  Generated into the app rather than shipped in an addon precisely for that union
+  — an addon never sees the host's, and could only answer
+  `Record<string, boolean>`. It returns `show` alone: sending `available` apart
+  from `capable` would tell every visitor which features exist but are dark.
+
+  The write half is the operator's, and lives in `@pikku/addon-admin` beside the
+  scope RPCs, under a new `admin:flags` scope. `flagList` reports `writable:
+false` rather than failing when flags come from a provider, because a provider's
+  own UI is its operator surface and a console full of buttons that 500 is worse
+  than a read-only tab. It still lists the flags: a source may report its declared
+  set through `declaredFlags()`, and each row carries `backed`, false where the
+  provider has never heard of a declared flag. That row is the one worth seeing —
+  an absent row fails open, so a dark launch nobody created in PostHog is already
+  live for everyone, and a store pikku owns can reconcile that on deploy where a
+  provider cannot.
+
+  On the client, `createFeatureFlags` fetches that map once and `useFeatureFlag`
+  reads it synchronously after, through the same provider the analytics client
+  hangs off. It takes a `bootstrap` map so a server-rendered page hydrates onto
+  the answer it already computed: without one there is a gap in which neither
+  default is right, since false hides a feature the user has and true flashes one
+  they do not. A failed refresh keeps the map already on screen rather than
+  relabelling every flag on a blip.
+
+## 0.12.109
+
+### Patch Changes
+
+- 54138b1: Product analytics moves into core behind a `scaffold.analytics` generator.
+
+  An app declares what it measures, and nothing else:
+
+  ```ts
+  import { defineAnalyticsEvents } from '#pikku/analytics'
+
+  export const analyticsEvents = defineAnalyticsEvents({
+    page_viewed: z.object({ path: z.string() }),
+    todo_created: z.object({ priority: z.enum(['low', 'medium', 'high']) }),
+  })
+  ```
+
+  The definer reaches an app through the generated `#pikku/analytics` leaf, the
+  way `defineFeatureFlags` reaches it through `#pikku/scopes` — an app declares
+  what it measures without importing out of core. The leaf is written on every
+  run, whatever `scaffold.analytics` says: the declaration is how a project names
+  what it measures, and the scaffold only decides whether an ingest wire is
+  generated for it. Its path is `analyticsTypesFile`, defaulting to
+  `<outDir>/analytics/pikku-analytics-types.gen.ts`. It carries the sink surface
+  as well as the definer — `AnalyticsService`, `AnalyticsRecord`,
+  `AnalyticsIdentity`, `AnalyticsClientContext`, `AnalyticsLog`,
+  `LoggerAnalyticsService` — because writing the destination events go to is the
+  other half of the same job, and both halves should come through one door.
+
+  The name is the key, so it is never repeated as a `z.literal` inside the
+  schema. Declare in as many modules as suits the project — a feature declares
+  its events beside its functions — and the CLI unions them into the generated
+  `/analytics` ingest and its schemas. The inspector finds the declarations the
+  way it finds every other wiring, so there is no path to configure.
+
+  Where events go is not part of the declaration. `services.analytics` is the
+  request-scoped buffer a function records into, typed against the declared
+  names:
+
+  ```ts
+  await analytics.record({ name: 'todo_created', priority: 'high' })
+  ```
+
+  It stamps identity, trace and wire fields from the invocation, buffers for the
+  length of the call and flushes once when it ends. Identity is always
+  server-side and never read from a request body, which is what makes the
+  unauthenticated ingest safe to expose.
+
+  The transport behind it is an `AnalyticsService` on singleton services — the
+  one swappable slot. With none wired the runner installs
+  `LoggerAnalyticsService`, so an app that turns the scaffold on can watch events
+  arrive without first choosing a store; a platform injects its own through
+  singleton services, and an app that wants neither sets `analyticsService` in
+  its own `services.ts`, which runs last and wins. There is no process-global
+  sink registry and no noop: events are never silently dropped.
+
+  The generated wire is added to the set of scaffolds the inspector reads.
+  Nothing imports it — it is a wiring, not a module anyone calls — so without
+  that the route was written and never registered: no HTTP wiring, no entry in
+  the fetch client, an endpoint that 404s.
+
+  No middleware is emitted with the wire: an origin lock rejects every native
+  client and is forgeable anyway, so guarding the route is the project's call.
+
+  `name` belongs to the event, not to its props. The generated union rebuilds
+  each member from the declared schema's shape and attaches the literal name
+  last, so a declaration that happens to carry a `name` prop of its own cannot
+  displace the discriminator the union is built on. Props schemas are typed to
+  require that shape, so a schema that has none — a union, a primitive — is
+  refused at the declaration rather than in generated code.
+
+## 0.12.108
+
+### Patch Changes
+
+- 4c7a1b5: Run the monorepo's own scripts through bun instead of yarn. What moves is the
+  package manager each package's `prepublishOnly` and build scripts invoke, plus
+  the two manifest fixes bun needs to resolve the tree: `uWebSockets.js` is
+  declared with an explicit `github:` specifier, and `@pikku/uws-handler` marks
+  its `uWebSockets.js` peer optional so a bun install of a consumer that brings
+  its own uWS app does not try to fetch it from the registry.
+
+  Three published behaviours change, all of them cases where an isolated
+  `node_modules` or bun as the runtime had been papered over by yarn's hoisting:
+
+  - `@pikku/migrator-sql` turns foreign keys on when it opens a sqlite database
+    through bun. `node:sqlite` enforces them by default and `bun:sqlite` does not,
+    which silently turned every `ON DELETE CASCADE` into a no-op under
+    `bunx --bun pikku`.
+  - `@pikku/cli` resolves a deploy provider against the project being deployed
+    rather than against wherever the CLI itself is installed, which is what its
+    own "is not installed" error asks the user to arrange.
+  - `@pikku/cli` treats a specifier a runtime hands straight back — bun does this
+    for the modules it implements itself — as not resolved from the project, so
+    it falls back rather than loading the runtime's own copy.
+
 ## 0.12.107
 
 ### Patch Changes

package/dist/analytics/analytics.d.ts

@@ -0,0 +1,6 @@
+import type { CoreUserSession, PikkuWire } from '../types/core.types.js';
+import type { Logger } from '../services/logger.js';
+import type { AnalyticsEventBase, AnalyticsEventInput, AnalyticsIdentityResolver, AnalyticsLog, AnalyticsService } from './analytics.types.js';
+/** Removes the discriminator, so `props` is free of the series key. */
+export declare const flattenAnalyticsEvent: (event: AnalyticsEventBase, at?: number) => AnalyticsEventInput;
+export declare const createInvocationAnalytics: (service: AnalyticsService, wire: PikkuWire<any, any, any, CoreUserSession>, logger?: Logger, resolveIdentity?: AnalyticsIdentityResolver) => AnalyticsLog;

package/dist/analytics/analytics.js

@@ -0,0 +1,58 @@
+/** Removes the discriminator, so `props` is free of the series key. */
+export const flattenAnalyticsEvent = (event, at) => {
+    const { name, ...props } = event;
+    return { name, props, ...(at === undefined ? {} : { at }) };
+};
+class InvocationAnalyticsLog {
+    service;
+    wire;
+    logger;
+    resolveIdentity;
+    buffer = [];
+    constructor(service, wire, logger, resolveIdentity) {
+        this.service = service;
+        this.wire = wire;
+        this.logger = logger;
+        this.resolveIdentity = resolveIdentity;
+    }
+    async record(event, client) {
+        this.buffer.push(this.resolveEvent(event, client));
+    }
+    async flush() {
+        if (this.buffer.length === 0)
+            return;
+        const batch = this.buffer.splice(0, this.buffer.length);
+        try {
+            await this.service.write(batch);
+        }
+        catch (error) {
+            const logger = this.wire.logger ?? this.logger;
+            logger?.warn?.('analytics flush failed', error);
+        }
+    }
+    async close() {
+        await this.flush();
+    }
+    resolveEvent(event, client) {
+        const session = this.wire.session;
+        const { name, props } = flattenAnalyticsEvent(event);
+        const resolved = this.resolveIdentity?.(this.wire);
+        return {
+            name,
+            props,
+            occurredAt: new Date().toISOString(),
+            ...(client?.at === undefined ? {} : { at: client.at }),
+            userIdentity: {
+                userId: session?.userId ?? null,
+                orgId: session?.orgId,
+                pikkuUserId: this.wire.pikkuUserId,
+                ...resolved,
+            },
+            traceId: this.wire.traceId,
+            functionId: this.wire.functionId,
+            wireType: this.wire.wireType,
+            source: client === undefined ? 'server' : 'client',
+        };
+    }
+}
+export const createInvocationAnalytics = (service, wire, logger, resolveIdentity) => new InvocationAnalyticsLog(service, wire, logger, resolveIdentity);

package/dist/analytics/analytics.types.d.ts

@@ -0,0 +1,156 @@
+import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core.types.js';
+/**
+ * The constraint a project's declared event union is checked against.
+ *
+ * Only `name` is fixed, because the name is the whole of what pikku itself
+ * reads — everything else on an event belongs to the app and to the sinks it
+ * wires, and narrowing it here would make the generic useless for anyone whose
+ * events carry more than a fixed set of props.
+ */
+export type AnalyticsEventBase = {
+    name: string;
+} & Record<string, unknown>;
+export interface AnalyticsEventInput {
+    name: string;
+    props?: Record<string, unknown>;
+    at?: number;
+}
+/**
+ * Stamped server-side from the session and never read from the request body,
+ * which is what makes an unauthenticated ingest safe to expose.
+ */
+export interface AnalyticsIdentity {
+    userId: string | null;
+    orgId?: string;
+    pikkuUserId?: string;
+    /**
+     * Identifiers a destination keys on that pikku does not mint — GA4's
+     * `client_id`, Meta's `fbp` and `fbc`, a vendor's own device id. All of them
+     * originate in the browser, and a sink that cannot produce one does not
+     * degrade, it sends nothing usable.
+     *
+     * Resolved server-side from first-party cookies on the request, never read
+     * from the event body, on the same reasoning as the rest of this object: a
+     * crafted client call must not be able to attribute an event to someone else.
+     */
+    vendorIds?: Record<string, string>;
+    /**
+     * A device-scoped id for a visitor with no session, minted by pikku rather
+     * than by a vendor.
+     *
+     * Distinct from `pikkuUserId`, which is derived from a session and is
+     * therefore absent for exactly the visitor this identifies. Without it a
+     * product-analytics sink has no honest option for anonymous traffic: keying
+     * on a shared literal collapses every visitor into one person, and dropping
+     * the event loses the whole pre-signup funnel.
+     */
+    anonymousId?: string;
+    /**
+     * What the visitor agreed to, keyed by purpose. A sink gated on a purpose
+     * absent here does not send.
+     *
+     * Open-ended rather than a fixed pair, because the purposes are the consent
+     * tool's vocabulary and jurisdictions do not agree on them. Undefined means
+     * the app wired no consent resolver, not that consent was refused — the gate
+     * belongs to the sink, which is where the app decides what absence means.
+     */
+    consent?: Record<string, boolean>;
+}
+/**
+ * Resolves the half of the identity pikku cannot know, from the wire.
+ *
+ * A function rather than a cookie-name map because consent tools do not store
+ * one boolean per cookie — a single encoded blob is more common — and a map
+ * could only express the easy case. {@link cookieAnalyticsIdentity} covers that
+ * easy case.
+ */
+export type AnalyticsIdentityResolver = (wire: PikkuWire<any, any, any, CoreUserSession>, 
+/**
+ * What the resolvers before this one produced, when composed. A minter needs
+ * it: whether it may write a cookie at all depends on consent another
+ * resolver read, and ordering is the only thing that can express that.
+ */
+resolved?: Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'>) => Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'> | undefined;
+/**
+ * What an event becomes once pikku has accepted it, and the only shape an
+ * {@link AnalyticsService} is ever handed.
+ *
+ * Distinct from {@link AnalyticsEventInput}, which is what a caller submits:
+ * the identity, the trace and the origin are stamped server-side on the way
+ * through, so a sink never has to trust — or re-derive — any of them.
+ */
+export interface AnalyticsRecord {
+    name: string;
+    props?: Record<string, unknown>;
+    occurredAt: string;
+    at?: number;
+    userIdentity: AnalyticsIdentity;
+    traceId?: string;
+    functionId?: string;
+    wireType?: PikkuWiringTypes;
+    source: 'server' | 'client';
+}
+/**
+ * Where accepted events go. Pikku validates, identifies and batches them; it
+ * does not store them.
+ *
+ * One method, taking a batch, because a batch is what a destination is always
+ * handed: the invocation buffers and flushes once, and a lone event is a batch
+ * of one. A single-event method beside it would be a second path every sink had
+ * to implement and every caller had to choose between.
+ */
+export interface AnalyticsService {
+    write(batch: AnalyticsRecord[]): Promise<void>;
+}
+/**
+ * One destination in a fan-out, with the events it is allowed to receive.
+ *
+ * `accepts` is the app's, not the sink's: which events a destination should get
+ * is policy — a product-analytics tool wants everything, an ad platform wants
+ * three conversions, and a consent gate reads the same way. What each event
+ * should look like once it gets there is the sink's, and lives in its mapper.
+ */
+export interface AnalyticsSink {
+    service: AnalyticsService;
+    accepts?: (record: AnalyticsRecord) => boolean;
+}
+/**
+ * Its presence, not `at`, is what marks a record as relayed from a browser — a
+ * beacon is free to omit `at`.
+ */
+export interface AnalyticsClientContext {
+    at?: number;
+}
+/**
+ * `services.analytics`: buffered for the invocation, flushed when it ends,
+ * always best-effort. `record` is a method rather than a property so an app can
+ * narrow `Events` in its own `SingletonServices`.
+ */
+export interface AnalyticsLog<Events extends AnalyticsEventBase = AnalyticsEventBase> {
+    record(event: Events, client?: AnalyticsClientContext): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * One declared event, as an administration surface sees it.
+ *
+ * Read off the declaration at build time rather than from a record: the catalog
+ * has to list an event nobody has fired yet, which is exactly the event someone
+ * is looking for when they open it.
+ */
+export interface AnalyticsEventMeta {
+    /** The event name a client emits, exactly as the declaration spells it. */
+    name: string;
+    /** The module holding the `defineAnalyticsEvents` call that declares it. */
+    file: string;
+    /** The name that module exports the declaration under. */
+    variable: string;
+    /**
+     * The event's props, keyed by name, valued with the schema's own source text
+     * (`z.string()`). Absent where the shape is not an object literal the
+     * inspector can read — a shared const, a union, a non-zod vendor.
+     */
+    props?: Record<string, string>;
+}
+/** Declared analytics events, keyed by event name. */
+export type AnalyticsEventsMeta = Record<string, AnalyticsEventMeta>;

package/dist/analytics/analytics.types.js

@@ -0,0 +1 @@
+export {};

package/dist/analytics/anonymous-analytics-identity.d.ts

@@ -0,0 +1,23 @@
+import type { SerializeOptions } from 'cookie';
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+export interface AnonymousAnalyticsIdentityOptions {
+    /** Cookie name. Defaults to `pikku_aid`. */
+    name?: string;
+    /**
+     * Consent purposes required before the cookie is written. Storing an
+     * analytics id on someone's device is the act consent governs, so this is
+     * usually set — and left unset only where the deployment meets a regulator's
+     * exemption for strictly necessary audience measurement.
+     */
+    requires?: string[];
+    cookie?: SerializeOptions;
+}
+/**
+ * Mints a device-scoped id for visitors who have no session yet.
+ *
+ * `httpOnly` by default, which is the honest reading of what this is for: no
+ * browser script needs it, and a cookie scripts cannot touch is both harder to
+ * misuse and not subject to the seven-day cap browsers place on script-set
+ * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ */
+export declare const anonymousAnalyticsIdentity: (options?: AnonymousAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

package/dist/analytics/anonymous-analytics-identity.js

@@ -0,0 +1,27 @@
+import { mintCookie } from './mint-cookie.js';
+const TWO_YEARS_SECONDS = 63_072_000;
+const DEFAULT_COOKIE = {
+    path: '/',
+    maxAge: TWO_YEARS_SECONDS,
+    sameSite: 'lax',
+    httpOnly: true,
+    secure: true,
+};
+/**
+ * Mints a device-scoped id for visitors who have no session yet.
+ *
+ * `httpOnly` by default, which is the honest reading of what this is for: no
+ * browser script needs it, and a cookie scripts cannot touch is both harder to
+ * misuse and not subject to the seven-day cap browsers place on script-set
+ * ones. An app that wants a vendor SDK to read it must opt out deliberately.
+ */
+export const anonymousAnalyticsIdentity = (options = {}) => {
+    return (wire, resolved) => {
+        const anonymousId = mintCookie(wire, options.name ?? 'pikku_aid', {
+            cookie: { ...DEFAULT_COOKIE, ...options.cookie },
+            requires: options.requires,
+            consent: resolved?.consent,
+        }, () => crypto.randomUUID());
+        return anonymousId === undefined ? undefined : { anonymousId };
+    };
+};

package/dist/analytics/compose-analytics-identity.d.ts

@@ -0,0 +1,14 @@
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+/**
+ * Runs resolvers in order, each seeing what the ones before it produced.
+ *
+ * Order is meaningful rather than incidental: a resolver that mints a cookie
+ * may only do so once consent has been read, so the resolver reading consent
+ * has to come first. Put the other way round, the minter sees no consent, mints
+ * nothing, and the app collects nothing — silently, which is why this threads
+ * state through instead of merging independent results.
+ *
+ * A later resolver wins a key it sets, so a minter's freshly created id
+ * replaces the absent one the cookie reader could not find.
+ */
+export declare const composeAnalyticsIdentity: (...resolvers: AnalyticsIdentityResolver[]) => AnalyticsIdentityResolver;