@pikku/core 0.12.106 → 0.12.111

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

@@ -0,0 +1,33 @@
+/**
+ * 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 const composeAnalyticsIdentity = (...resolvers) => {
+    return (wire, initial) => {
+        let resolved = initial ?? {};
+        for (const resolver of resolvers) {
+            const next = resolver(wire, resolved);
+            if (!next)
+                continue;
+            resolved = {
+                ...resolved,
+                ...next,
+                ...(next.vendorIds === undefined && resolved.vendorIds === undefined
+                    ? {}
+                    : { vendorIds: { ...resolved.vendorIds, ...next.vendorIds } }),
+                ...(next.consent === undefined && resolved.consent === undefined
+                    ? {}
+                    : { consent: { ...resolved.consent, ...next.consent } }),
+            };
+        }
+        return Object.keys(resolved).length === 0 ? undefined : resolved;
+    };
+};

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

@@ -0,0 +1,24 @@
+import type { AnalyticsIdentityResolver } from './analytics.types.js';
+export interface CookieAnalyticsIdentityOptions {
+    /** Identity key to read it from, e.g. `{ gaClientId: '_ga' }`. */
+    vendorIds?: Record<string, string>;
+    /**
+     * Consent purpose to the cookie that grants it. The purpose is true only when
+     * the cookie is present and is not a recognised denial (`'0'`, `'false'`,
+     * `'denied'`), so a consent tool that writes a refusal rather than deleting
+     * the cookie is read as a refusal.
+     */
+    consent?: Record<string, string>;
+}
+/**
+ * Reads the browser-originated half of the identity off first-party cookies.
+ *
+ * Covers the common case only. A consent tool that packs every purpose into one
+ * encoded blob needs its own resolver — which is why the resolver is a function
+ * and this is a helper rather than the mechanism.
+ *
+ * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
+ * worker have no browser behind them, so any vendor id they produced would be
+ * invented.
+ */
+export declare const cookieAnalyticsIdentity: (options: CookieAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

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

@@ -0,0 +1,37 @@
+const DENIALS = new Set(['0', 'false', 'denied', 'deny', 'no']);
+/**
+ * Reads the browser-originated half of the identity off first-party cookies.
+ *
+ * Covers the common case only. A consent tool that packs every purpose into one
+ * encoded blob needs its own resolver — which is why the resolver is a function
+ * and this is a helper rather than the mechanism.
+ *
+ * Resolves nothing off an HTTP wire, which is correct: a cron task and a queue
+ * worker have no browser behind them, so any vendor id they produced would be
+ * invented.
+ */
+export const cookieAnalyticsIdentity = (options) => {
+    return (wire) => {
+        const request = wire.http?.request;
+        if (!request)
+            return undefined;
+        const vendorIds = {};
+        for (const [key, cookieName] of Object.entries(options.vendorIds ?? {})) {
+            const value = request.cookie(cookieName);
+            if (value) {
+                vendorIds[key] = value;
+            }
+        }
+        const consent = {};
+        for (const [purpose, cookieName] of Object.entries(options.consent ?? {})) {
+            const value = request.cookie(cookieName);
+            if (value !== null) {
+                consent[purpose] = !DENIALS.has(value.toLowerCase());
+            }
+        }
+        return {
+            ...(Object.keys(vendorIds).length === 0 ? {} : { vendorIds }),
+            ...(Object.keys(consent).length === 0 ? {} : { consent }),
+        };
+    };
+};

package/dist/analytics/define-analytics-events.d.ts

@@ -0,0 +1,22 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+/**
+ * The schema for one event's props. The generated ingest rebuilds each member
+ * of the union as `z.object(schema.shape)` so it can attach the event name, so
+ * a schema with no `shape` — a union, a primitive, a schema from a library
+ * that does not expose one — is not something an event can be declared with,
+ * and saying so here fails at the declaration rather than in generated code.
+ */
+export type AnalyticsEventPropsSchema = StandardSchemaV1 & {
+    shape: Record<string, unknown>;
+};
+/** Events keyed by name; each value is the schema for that event's props. */
+export type AnalyticsEventDefinitions = Record<string, AnalyticsEventPropsSchema>;
+/**
+ * Declare what a module can measure. Call it as often as suits the project; the
+ * CLI unions every declaration into the ingest schema.
+ *
+ * It must stay an exported const — the schema pipeline reads the value by name.
+ * It registers nothing at runtime: where events go is an `AnalyticsService` on
+ * singleton services.
+ */
+export declare const defineAnalyticsEvents: <const Events extends AnalyticsEventDefinitions>(events: Events) => Events;

package/dist/analytics/define-analytics-events.js

@@ -0,0 +1,9 @@
+/**
+ * Declare what a module can measure. Call it as often as suits the project; the
+ * CLI unions every declaration into the ingest schema.
+ *
+ * It must stay an exported const — the schema pipeline reads the value by name.
+ * It registers nothing at runtime: where events go is an `AnalyticsService` on
+ * singleton services.
+ */
+export const defineAnalyticsEvents = (events) => events;

package/dist/analytics/fan-out-analytics.d.ts

@@ -0,0 +1,15 @@
+import type { AnalyticsService, AnalyticsSink } from './analytics.types.js';
+/**
+ * One `AnalyticsService` over several destinations.
+ *
+ * A composite rather than a change to the interface, so a single-destination
+ * app never meets it and a sink is the same class whether it runs alone or
+ * beside three others.
+ *
+ * Settled, not awaited in sequence: `flush()` runs inside the invocation, so a
+ * vendor that is slow must not add its latency to the request and a vendor that
+ * is down must not cost the others their events. A destination that throws is
+ * reported by the caller's existing flush guard, which already treats analytics
+ * as best-effort.
+ */
+export declare const fanOutAnalytics: (sinks: ReadonlyArray<AnalyticsSink | AnalyticsService>) => AnalyticsService;

package/dist/analytics/fan-out-analytics.js

@@ -0,0 +1,36 @@
+/**
+ * One `AnalyticsService` over several destinations.
+ *
+ * A composite rather than a change to the interface, so a single-destination
+ * app never meets it and a sink is the same class whether it runs alone or
+ * beside three others.
+ *
+ * Settled, not awaited in sequence: `flush()` runs inside the invocation, so a
+ * vendor that is slow must not add its latency to the request and a vendor that
+ * is down must not cost the others their events. A destination that throws is
+ * reported by the caller's existing flush guard, which already treats analytics
+ * as best-effort.
+ */
+export const fanOutAnalytics = (sinks) => {
+    const resolved = sinks.map((sink) => 'service' in sink ? sink : { service: sink });
+    return {
+        async write(batch) {
+            if (batch.length === 0)
+                return;
+            const results = await Promise.allSettled(
+            // `accepts` is app code and runs inside this map. Thrown
+            // synchronously it would escape before `allSettled` was ever called,
+            // and every destination after it in the list would lose the batch.
+            resolved.map(async ({ service, accepts }) => {
+                const records = accepts ? batch.filter(accepts) : batch;
+                if (records.length === 0)
+                    return;
+                await service.write(records);
+            }));
+            const failures = results.filter((result) => result.status === 'rejected');
+            if (failures.length > 0) {
+                throw new AggregateError(failures.map((failure) => failure.reason), `${failures.length} of ${resolved.length} analytics destinations failed`);
+            }
+        },
+    };
+};

package/dist/analytics/index.d.ts

@@ -0,0 +1,13 @@
+export type { AnalyticsClientContext, AnalyticsEventBase, AnalyticsEventMeta, AnalyticsEventsMeta, AnalyticsEventInput, AnalyticsIdentity, AnalyticsLog, AnalyticsIdentityResolver, AnalyticsRecord, AnalyticsService, AnalyticsSink, } from './analytics.types.js';
+export { createInvocationAnalytics, flattenAnalyticsEvent, } from './analytics.js';
+export { LoggerAnalyticsService } from './logger-analytics-service.js';
+export { defineAnalyticsEvents } from './define-analytics-events.js';
+export type { AnalyticsEventDefinitions, AnalyticsEventPropsSchema, } from './define-analytics-events.js';
+export { fanOutAnalytics } from './fan-out-analytics.js';
+export { cookieAnalyticsIdentity } from './cookie-analytics-identity.js';
+export type { CookieAnalyticsIdentityOptions } from './cookie-analytics-identity.js';
+export { mintCookie, randomDigits } from './mint-cookie.js';
+export type { MintCookieOptions } from './mint-cookie.js';
+export { composeAnalyticsIdentity } from './compose-analytics-identity.js';
+export { anonymousAnalyticsIdentity } from './anonymous-analytics-identity.js';
+export type { AnonymousAnalyticsIdentityOptions } from './anonymous-analytics-identity.js';

package/dist/analytics/index.js

@@ -0,0 +1,8 @@
+export { createInvocationAnalytics, flattenAnalyticsEvent, } from './analytics.js';
+export { LoggerAnalyticsService } from './logger-analytics-service.js';
+export { defineAnalyticsEvents } from './define-analytics-events.js';
+export { fanOutAnalytics } from './fan-out-analytics.js';
+export { cookieAnalyticsIdentity } from './cookie-analytics-identity.js';
+export { mintCookie, randomDigits } from './mint-cookie.js';
+export { composeAnalyticsIdentity } from './compose-analytics-identity.js';
+export { anonymousAnalyticsIdentity } from './anonymous-analytics-identity.js';

package/dist/analytics/logger-analytics-service.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from '../services/logger.js';
+import type { AnalyticsRecord, AnalyticsService } from './analytics.types.js';
+/**
+ * What an app gets before it has chosen a store. There is deliberately no noop:
+ * a validated wire with nowhere for the events to go is indistinguishable from
+ * a broken one.
+ *
+ * At `debug` so attaching a real store does not report every event twice.
+ */
+export declare class LoggerAnalyticsService implements AnalyticsService {
+    private readonly logger;
+    constructor(logger: Logger);
+    write(batch: AnalyticsRecord[]): Promise<void>;
+}

package/dist/analytics/logger-analytics-service.js

@@ -0,0 +1,23 @@
+/**
+ * What an app gets before it has chosen a store. There is deliberately no noop:
+ * a validated wire with nowhere for the events to go is indistinguishable from
+ * a broken one.
+ *
+ * At `debug` so attaching a real store does not report every event twice.
+ */
+export class LoggerAnalyticsService {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async write(batch) {
+        for (const event of batch) {
+            this.logger.debug(`analytics: ${event.name}`, {
+                ...event.props,
+                userId: event.userIdentity.userId,
+                source: event.source,
+                ...(event.at === undefined ? {} : { at: event.at }),
+            });
+        }
+    }
+}

package/dist/analytics/mint-cookie.d.ts

@@ -0,0 +1,44 @@
+import type { SerializeOptions } from 'cookie';
+import type { CoreUserSession, PikkuWire } from '../types/core.types.js';
+type AnyWire = PikkuWire<any, any, any, CoreUserSession>;
+export interface MintCookieOptions {
+    /** Cookie attributes. Long-lived and first-party is the usual shape. */
+    cookie: SerializeOptions;
+    /**
+     * Purposes that must all be `true` before anything is written. Writing the
+     * cookie IS the act consent governs, so a minter that runs before the banner
+     * is answered has already done the thing the send gate was meant to prevent.
+     */
+    requires?: string[];
+    consent?: Record<string, boolean>;
+    /**
+     * Replace the cookie already on the device rather than returning it.
+     *
+     * For the case where the request itself carries something newer than what is
+     * stored — Meta's `_fbc` derives from the `fbclid` on the current URL, and
+     * keeping an older click would attribute the conversion to the wrong ad.
+     */
+    overwrite?: boolean;
+}
+/**
+ * Reads a first-party cookie, creating and setting it when absent.
+ *
+ * This is how an app tracks a visitor with no vendor SDK on the page: the
+ * identifiers GA4 and Meta key on are ordinary first-party cookies in a
+ * documented format, and nothing requires a browser script to be the one that
+ * writes them. It is the mechanism behind server-side tagging, and the reason
+ * pikku can offer it as a wired service rather than a second container to run.
+ *
+ * Minted once per wire, not once per call. The resolver runs for every event,
+ * and a second mint within one request would hand the same visitor two
+ * identities — which reads downstream as two people rather than as a bug.
+ *
+ * Writes nothing on a wire with no HTTP response, and nothing once the response
+ * has been sent; a cron task and a queue worker have no browser to store it,
+ * and a stream's headers are long gone. Both return undefined rather than
+ * pretending.
+ */
+export declare const mintCookie: (wire: AnyWire, name: string, options: MintCookieOptions, mint: () => string) => string | undefined;
+/** Cryptographically random digits, the shape both vendor formats use. */
+export declare const randomDigits: (length: number) => string;
+export {};

package/dist/analytics/mint-cookie.js

@@ -0,0 +1,55 @@
+const minted = new WeakMap();
+const permitted = (requires, consent) => {
+    if (!requires || requires.length === 0)
+        return true;
+    return requires.every((purpose) => consent?.[purpose] === true);
+};
+/**
+ * Reads a first-party cookie, creating and setting it when absent.
+ *
+ * This is how an app tracks a visitor with no vendor SDK on the page: the
+ * identifiers GA4 and Meta key on are ordinary first-party cookies in a
+ * documented format, and nothing requires a browser script to be the one that
+ * writes them. It is the mechanism behind server-side tagging, and the reason
+ * pikku can offer it as a wired service rather than a second container to run.
+ *
+ * Minted once per wire, not once per call. The resolver runs for every event,
+ * and a second mint within one request would hand the same visitor two
+ * identities — which reads downstream as two people rather than as a bug.
+ *
+ * Writes nothing on a wire with no HTTP response, and nothing once the response
+ * has been sent; a cron task and a queue worker have no browser to store it,
+ * and a stream's headers are long gone. Both return undefined rather than
+ * pretending.
+ */
+export const mintCookie = (wire, name, options, mint) => {
+    const existing = options.overwrite
+        ? null
+        : wire.http?.request?.cookie(name);
+    if (existing)
+        return existing;
+    const cache = minted.get(wire) ?? new Map();
+    const already = cache.get(name);
+    if (already)
+        return already;
+    const response = wire.http?.response;
+    if (!response)
+        return undefined;
+    if (!permitted(options.requires, options.consent))
+        return undefined;
+    const value = mint();
+    response.cookie(name, value, options.cookie);
+    cache.set(name, value);
+    minted.set(wire, cache);
+    return value;
+};
+/** Cryptographically random digits, the shape both vendor formats use. */
+export const randomDigits = (length) => {
+    const bytes = new Uint8Array(length);
+    crypto.getRandomValues(bytes);
+    let digits = '';
+    for (const byte of bytes) {
+        digits += String(byte % 10);
+    }
+    return digits;
+};

package/dist/errors/errors.d.ts

@@ -35,6 +35,13 @@ export declare class MissingScopeError extends PikkuError {
     };
     constructor(scope: string);
 }
+export declare class FeatureUnavailableError extends PikkuError {
+    payload: {
+        error: 'feature_unavailable';
+        feature: string;
+    };
+    constructor(feature: string);
+}
 export declare class ReadonlySessionError extends PikkuError {
 }
 export declare class InvalidOriginError extends PikkuError {

package/dist/errors/errors.js

@@ -87,6 +87,23 @@ addError(MissingScopeError, {
     status: 403,
     message: 'The session does not hold a scope required by this function.',
 });
+export class FeatureUnavailableError extends PikkuError {
+    payload;
+    constructor(feature) {
+        super(`Feature is currently unavailable: ${feature}`);
+        this.payload = {
+            error: 'feature_unavailable',
+            feature,
+        };
+    }
+}
+// 503 and not 403: a killed feature is a server-side, temporary, not-your-fault
+// condition, and it should be retryable and monitorable as one. A 403 here
+// would page the wrong team and tell the caller to fix something they cannot.
+addError(FeatureUnavailableError, {
+    status: 503,
+    message: 'This feature is switched off.',
+});
 export class ReadonlySessionError extends PikkuError {
 }
 addError(ReadonlySessionError, {

package/dist/function/function-meta.types.d.ts

@@ -25,6 +25,8 @@ export type FunctionRuntimeMeta = {
     outputSchemaName: string | null;
     /** Scopes the session must hold to run this function. All are required (AND). */
     scopes?: string[];
+    /** The feature this function belongs to. Checked for availability only. */
+    featureFlag?: string;
     expose?: boolean;
     /**
      * A sessionless function's own `auth: true`. `sessionless` carries the

package/dist/function/function-runner.js

@@ -9,9 +9,12 @@ import { parseVersionedId } from '../version.js';
 import { PikkuSessionService } from '../services/user-session-service.js';
 import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js';
 import { verifyScopes } from '../scopes.js';
+import { assertFeatureAvailable } from '../wirings/flag/assert-feature-available.js';
 import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
 import { createInvocationAudit, resolveAuditConfig, } from '../services/audit-service.js';
+import { createInvocationAnalytics } from '../analytics/analytics.js';
+import { LoggerAnalyticsService } from '../analytics/logger-analytics-service.js';
 import { rpcService } from '../wirings/rpc/rpc-runner.js';
 import { getOrCreatePackageSingletonServices } from '../wirings/addon/addon-runner.js';
 import { resolveAddonAuth, resolveAddonFunctionTarget, resolveAddonScopes, resolveAddonTagMiddleware, } from '../wirings/addon/wire-addon.js';
@@ -209,6 +212,16 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         verifyScopes(addonScopes.length > 0
             ? [...addonScopes, ...(functionScopes ?? [])]
             : functionScopes, session);
+        const featureFlag = funcConfig.featureFlag ?? funcMeta.featureFlag;
+        if (featureFlag) {
+            // The host's source, not the package's: a `featureFlag:` on an addon
+            // function names a flag the consuming application declared and its
+            // operators switch. A package factory builds its own services and has no
+            // reason to carry one, and reading that would leave every addon gate
+            // open.
+            await assertFeatureAvailable(featureFlag, singletonServices.featureFlags ??
+                resolvedSingletonServices.featureFlags, session);
+        }
         let actualData = await data();
         const inputSchemaName = funcMeta.inputSchemaName;
         if (inputSchemaName) {
@@ -228,6 +241,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         });
         let wireServices;
         let invocationAuditLog;
+        let invocationAnalytics;
         try {
             wireServices = (await resolvedCreateWireServices?.(resolvedSingletonServices, invocationWire));
             let services = wireServices && Object.keys(wireServices).length > 0
@@ -240,6 +254,20 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
                 invocationAuditLog = createInvocationAudit(resolvedSingletonServices.audit, invocationWire, resolvedSingletonServices.logger);
                 services = { ...services, auditLog: invocationAuditLog };
             }
+            // Unconditional, unlike the audit — every function can record. Built on
+            // first access, since most invocations record nothing.
+            if (!services.analytics) {
+                services = { ...services };
+                Object.defineProperty(services, 'analytics', {
+                    get() {
+                        invocationAnalytics ??= createInvocationAnalytics(resolvedSingletonServices.analyticsService ??
+                            new LoggerAnalyticsService(resolvedSingletonServices.logger), invocationWire, resolvedSingletonServices.logger, resolvedSingletonServices.analyticsIdentity);
+                        return invocationAnalytics;
+                    },
+                    configurable: true,
+                    enumerable: true,
+                });
+            }
             const callerPackageName = funcPackageName;
             Object.defineProperty(invocationWire, 'rpc', {
                 get() {
@@ -259,6 +287,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         finally {
             // Flush the runner-installed audit buffer before wire services close.
             await invocationAuditLog?.close();
+            await invocationAnalytics?.close();
             if (wireServices && Object.keys(wireServices).length > 0) {
                 await closeWireServices(resolvedSingletonServices.logger, wireServices);
             }

package/dist/function/functions.types.d.ts

@@ -15,7 +15,7 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessS
     name?: string;
     description?: string;
 };
-export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session"> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, "session">>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
+export declare const pikkuPermission: <In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'> = PickRequired<PikkuWire<In, never, false, any, PikkuRPC, never, never>, 'session'>>(permission: CorePikkuPermission<In, Services, Wire> | CorePikkuPermissionConfig<In, Services, Wire>) => CorePikkuPermission<In, Services, Wire>;
 export type CorePikkuPermissionFactory<In = any, Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Wire extends PikkuWire<In, never, false, any, PikkuRPC, never, never> = PikkuWire<In, never, false, any, PikkuRPC, never, never>> = (input: In) => CorePikkuPermission<any, Services, Wire>;
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
@@ -47,7 +47,7 @@ export type CorePermissionGroup<PikkuPermission = CorePikkuPermission<any>> = Re
  * it is never recorded and never replayed.
  */
 export type CorePikkuFunctionHook<Services = any, Data = any, Wire = any> = (services: Services, data: Data, wire: Wire) => Promise<void> | void;
-export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string> = {
+export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any, any, any, any, any> | CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, Scope extends string = string, FeatureFlagName extends string = string> = {
     /** A human name for this function, shown wherever it is listed rather than called. */
     title?: string;
     /** What the function does. An agent choosing between tools reads this, so it is worth more care than a comment would be. */
@@ -128,6 +128,20 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
     auth?: boolean;
     /** Scopes the session must hold. All are required, and checked before `permissions`, which OR together — a scope only narrows access. */
     scopes?: Scope[];
+    /**
+     * The feature this function belongs to. Singular: a function implements part
+     * of one feature, and needing two is a sign it does two things.
+     *
+     * Resolved at runtime on every call, unlike `tags:` — a flag is
+     * meant to be flipped in a running system, so nothing here filters a build.
+     *
+     * Checked for AVAILABILITY only, never capability — if the runner enforced
+     * the capability half a flag would become a second authorization path with
+     * OR-ish semantics against `scopes:`. Authorization is always `scopes:`.
+     * Runs after `scopes:` so an unauthorized caller gets a 403 whether or not
+     * the feature is up, rather than learning that it exists and is off.
+     */
+    featureFlag?: FeatureFlagName;
     /** Checks that run before the body. Grouped names OR together, so any one passing admits the caller; use `scopes` to require rather than offer. */
     permissions?: CorePermissionGroup<PikkuPermission>;
     /** Wraps this function wherever it is called from, unlike wiring middleware which only wraps one route into it. */
@@ -148,5 +162,10 @@ export type CorePikkuFunctionConfig<PikkuFunction extends CorePikkuFunction<any,
  * so an anonymous caller holds none and satisfies none — a sessionless function
  * with scopes rejects every caller it exists to serve. Gate it with
  * `permissions`, which receive the optional session and may pass anonymous.
+ *
+ * `featureFlag` is deliberately NOT omitted. It reads the config snapshot
+ * rather than the session, so it applies identically to a cron task, a queue
+ * worker and a webhook — which is where a kill switch matters most, since
+ * nobody is watching a UI to notice the feature is off.
  */
-export type CorePikkuSessionlessFunctionConfig<PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware, InputSchema, OutputSchema>, 'scopes'>;
+export type CorePikkuSessionlessFunctionConfig<PikkuFunction extends CorePikkuFunctionSessionless<any, any, any, any, any>, PikkuPermission extends CorePikkuPermission<any, any, any> = CorePikkuPermission<any>, PikkuMiddleware extends CorePikkuMiddleware<any, any> = CorePikkuMiddleware<any, any>, InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, FeatureFlagName extends string = string> = Omit<CorePikkuFunctionConfig<PikkuFunction, PikkuPermission, PikkuMiddleware, InputSchema, OutputSchema, string, FeatureFlagName>, 'scopes'>;

package/dist/middleware/auth-apikey.d.ts

@@ -6,5 +6,5 @@
  */
 export declare const authAPIKey: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
     /** Where to look: the `x-api-key` header, the `apiKey` query param, or both. */
-    source: "header" | "query" | "all";
+    source: 'header' | 'query' | 'all';
 }>;

package/dist/pikku-state.d.ts

@@ -7,5 +7,5 @@ export declare const resetPikkuState: () => void;
 export declare const getSingletonServices: () => CoreSingletonServices;
 export declare const setSingletonServices: (services: CoreSingletonServices) => void;
 export declare const getCreateWireServices: () => CreateWireServices | undefined;
-export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState["package"]["factories"]>) => void;
+export declare const addPackageServiceFactories: (packageName: string, factories: NonNullable<PikkuPackageState['package']['factories']>) => void;
 export type { PikkuPackageState } from './types/state.types.js';

package/dist/scopes.d.ts

@@ -4,6 +4,17 @@ import type { CoreUserSession } from './types/core.types.js';
  * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export declare const hasScopes: (required: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
+/**
+ * True when `held` satisfies AT LEAST ONE of `candidates`, with the same
+ * parent/wildcard rules as {@link hasScopes}.
+ *
+ * The OR counterpart to {@link hasScopes}, for a feature flag's `anyOf`: a flag
+ * usually reveals one entry point several roles can reach, so requiring all of
+ * them would hide it from everyone who can actually use it. Fails closed — an
+ * empty or absent `candidates` is satisfied by nothing, because "any of
+ * nothing" has no member that could hold.
+ */
+export declare const hasAnyScope: (candidates: readonly string[] | undefined, held: Iterable<string> | undefined) => boolean;
 /**
  * Throws {@link MissingScopeError} naming the first scope the session does not
  * hold. Fails closed: no session, or a session without `scopes`, satisfies

package/dist/scopes.js

@@ -36,6 +36,23 @@ const firstUnsatisfied = (required, held) => {
  * than enforcing. Fails closed; an empty `required` is satisfied by anything.
  */
 export const hasScopes = (required, held) => firstUnsatisfied(required, held) === null;
+/**
+ * True when `held` satisfies AT LEAST ONE of `candidates`, with the same
+ * parent/wildcard rules as {@link hasScopes}.
+ *
+ * The OR counterpart to {@link hasScopes}, for a feature flag's `anyOf`: a flag
+ * usually reveals one entry point several roles can reach, so requiring all of
+ * them would hide it from everyone who can actually use it. Fails closed — an
+ * empty or absent `candidates` is satisfied by nothing, because "any of
+ * nothing" has no member that could hold.
+ */
+export const hasAnyScope = (candidates, held) => {
+    if (!candidates || candidates.length === 0) {
+        return false;
+    }
+    const grants = new Set(held ?? []);
+    return candidates.some((scope) => holds(grants, scope));
+};
 /**
  * Throws {@link MissingScopeError} naming the first scope the session does not
  * hold. Fails closed: no session, or a session without `scopes`, satisfies

package/dist/services/credential-wire-service.d.ts

@@ -42,5 +42,5 @@ export declare function createMiddlewareCredentialWireProps(credentialWire: Pikk
 export declare function createWireServicesCredentialWireProps(credentialWire: PikkuCredentialWireService, allowedNames?: string[]): {
     setCredential: (name: string, value: unknown) => void;
     getCredential: <T = unknown>(name: string) => T | Promise<T | null> | null;
-    getCredentials: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+    getCredentials: () => Promise<Record<string, unknown>> | Record<string, unknown>;
 };