@pikku/core 0.12.135 → 0.12.136

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.12.136
+
+### Patch Changes
+
+- 149faae: Webhook `receive` steps lose their boilerplate. `pikkuWebhookReceive` (from `#pikku/trigger` or `#pikku/addon/trigger`) declares one: it is public, typed to the raw request with a required `http`, and never registered as an RPC, and the inspector rejects a `receive` declared with any other wrapper. `parseJson` (in `@pikku/core/utils`, generated as `#pikku/utils` and `#pikku/addon/utils`) parses text or bytes and answers a body that is not JSON with a 400. A webhook source whose `method` includes `'head'` answers HEAD probes itself with a 200.
+
+  `receive` no longer returns `{ respond }`: a handshake returns nothing and writes its answer to `http.response`, like any other HTTP function. The webhook route no longer returns a fetch `Response` either. An HTTP function that returns nothing is now answered with whatever status its response has (200 unless it set another), no longer a forced 204. A webhook receive is also left out of contract versioning, since nothing but its own route calls it.
+
 ## 0.12.135
 
 ### Patch Changes

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

@@ -8,6 +8,7 @@ import type { CoreUserSession, PikkuWire, PikkuWiringTypes } from '../types/core
  * events carry more than a fixed set of props.
  */
 export type AnalyticsEventBase = {
+    /** The event name, as declared in `defineAnalyticsEvents`. */
     name: string;
 } & Record<string, unknown>;
 export interface AnalyticsEventInput {
@@ -20,8 +21,11 @@ export interface AnalyticsEventInput {
  * which is what makes an unauthenticated ingest safe to expose.
  */
 export interface AnalyticsIdentity {
+    /** The session's user id, or null for a visitor with no session. */
     userId: string | null;
+    /** The session's organization, when it has one. */
     orgId?: string;
+    /** The pikku user the session resolves to; absent without a session. */
     pikkuUserId?: string;
     /**
      * Identifiers a destination keys on that pikku does not mint — GA4's
@@ -80,14 +84,23 @@ resolved?: Pick<AnalyticsIdentity, 'vendorIds' | 'consent' | 'anonymousId'>) =>
  * through, so a sink never has to trust — or re-derive — any of them.
  */
 export interface AnalyticsRecord {
+    /** The event name. */
     name: string;
+    /** The validated props the event carried. */
     props?: Record<string, unknown>;
+    /** When the server accepted the event, as an ISO timestamp. */
     occurredAt: string;
+    /** When a browser says it happened, in epoch milliseconds; only on relayed events. */
     at?: number;
+    /** Who the event is attributed to, stamped from the session and cookies. */
     userIdentity: AnalyticsIdentity;
+    /** The trace the emitting invocation belongs to. */
     traceId?: string;
+    /** The function that recorded the event, when one did. */
     functionId?: string;
+    /** The kind of wire the event came in on. */
     wireType?: PikkuWiringTypes;
+    /** `client` when relayed from a browser, `server` when a function recorded it. */
     source: 'server' | 'client';
 }
 /**
@@ -100,6 +113,7 @@ export interface AnalyticsRecord {
  * to implement and every caller had to choose between.
  */
 export interface AnalyticsService {
+    /** Delivers one batch of accepted records; a rejection is logged, never surfaced to the caller. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }
 /**
@@ -111,7 +125,9 @@ export interface AnalyticsService {
  * should look like once it gets there is the sink's, and lives in its mapper.
  */
 export interface AnalyticsSink {
+    /** The destination the filtered records are written to. */
     service: AnalyticsService;
+    /** Returns true for the records this destination should get; omit to send everything. */
     accepts?: (record: AnalyticsRecord) => boolean;
 }
 /**
@@ -119,6 +135,7 @@ export interface AnalyticsSink {
  * beacon is free to omit `at`.
  */
 export interface AnalyticsClientContext {
+    /** When the browser says the event happened, in epoch milliseconds. */
     at?: number;
 }
 /**
@@ -127,8 +144,11 @@ export interface AnalyticsClientContext {
  * narrow `Events` in its own `SingletonServices`.
  */
 export interface AnalyticsLog<Events extends AnalyticsEventBase = AnalyticsEventBase> {
+    /** Buffers an event for the invocation; pass `client` when relaying one from a browser. */
     record(event: Events, client?: AnalyticsClientContext): Promise<void>;
+    /** Writes what is buffered to the service now, rather than when the invocation ends. */
     flush(): Promise<void>;
+    /** Flushes and stops accepting events; called for you when the invocation ends. */
     close(): Promise<void>;
 }
 /**

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

@@ -19,5 +19,7 @@ export interface AnonymousAnalyticsIdentityOptions {
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const anonymousAnalyticsIdentity: (options?: AnonymousAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

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

@@ -14,6 +14,8 @@ const DEFAULT_COOKIE = {
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const anonymousAnalyticsIdentity = (options = {}) => {
     return (wire, resolved) => {

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

@@ -10,5 +10,7 @@ import type { AnalyticsIdentityResolver } from './analytics.types.js';
  *
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const composeAnalyticsIdentity: (...resolvers: AnalyticsIdentityResolver[]) => AnalyticsIdentityResolver;

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

@@ -9,6 +9,8 @@
  *
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const composeAnalyticsIdentity = (...resolvers) => {
     return (wire, initial) => {

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

@@ -20,5 +20,7 @@ export interface CookieAnalyticsIdentityOptions {
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export declare const cookieAnalyticsIdentity: (options: CookieAnalyticsIdentityOptions) => AnalyticsIdentityResolver;

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

@@ -9,6 +9,8 @@ const DENIALS = new Set(['0', 'false', 'denied', 'deny', 'no']);
  * 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.
+ *
+ * @example snippet: analyticsIdentity
  */
 export const cookieAnalyticsIdentity = (options) => {
     return (wire) => {

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

@@ -7,6 +7,7 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
  * and saying so here fails at the declaration rather than in generated code.
  */
 export type AnalyticsEventPropsSchema = StandardSchemaV1 & {
+    /** The object schema's fields, which the CLI reads to list an event's props. */
     shape: Record<string, unknown>;
 };
 /** Events keyed by name; each value is the schema for that event's props. */
@@ -18,5 +19,7 @@ export type AnalyticsEventDefinitions = Record<string, AnalyticsEventPropsSchema
  * 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.
+ *
+ * @example snippet: analyticsEvents
  */
 export declare const defineAnalyticsEvents: <const Events extends AnalyticsEventDefinitions>(events: Events) => Events;

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

@@ -5,5 +5,7 @@
  * 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.
+ *
+ * @example snippet: analyticsEvents
  */
 export const defineAnalyticsEvents = (events) => events;

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

@@ -11,5 +11,7 @@ import type { AnalyticsService, AnalyticsSink } from './analytics.types.js';
  * 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.
+ *
+ * @example snippet: shopServices
  */
 export declare const fanOutAnalytics: (sinks: ReadonlyArray<AnalyticsSink | AnalyticsService>) => AnalyticsService;

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

@@ -10,6 +10,8 @@
  * 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.
+ *
+ * @example snippet: shopServices
  */
 export const fanOutAnalytics = (sinks) => {
     const resolved = sinks.map((sink) => 'service' in sink ? sink : { service: sink });

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

@@ -9,6 +9,8 @@ import type { AnalyticsRecord, AnalyticsService } from './analytics.types.js';
  */
 export declare class LoggerAnalyticsService implements AnalyticsService {
     private readonly logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger: Logger);
+    /** Logs each record in the batch at `debug`. */
     write(batch: AnalyticsRecord[]): Promise<void>;
 }

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

@@ -7,9 +7,11 @@
  */
 export class LoggerAnalyticsService {
     logger;
+    /** @param logger Receives each event at `debug`. */
     constructor(logger) {
         this.logger = logger;
     }
+    /** Logs each record in the batch at `debug`. */
     async write(batch) {
         for (const event of batch) {
             this.logger.debug(`analytics: ${event.name}`, {

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

@@ -10,6 +10,7 @@ export interface MintCookieOptions {
      * is answered has already done the thing the send gate was meant to prevent.
      */
     requires?: string[];
+    /** What the visitor agreed to, as resolved by an earlier resolver; `requires` is checked against it. */
     consent?: Record<string, boolean>;
     /**
      * Replace the cookie already on the device rather than returning it.
@@ -37,8 +38,14 @@ export interface MintCookieOptions {
  * 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.
+ *
+ * @example snippet: mintVendorCookie
  */
 export declare const mintCookie: (wire: AnyWire, name: string, options: MintCookieOptions, mint: () => string) => string | undefined;
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export declare const randomDigits: (length: number) => string;
 export {};

package/dist/analytics/mint-cookie.js

@@ -21,11 +21,11 @@ const permitted = (requires, consent) => {
  * 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.
+ *
+ * @example snippet: mintVendorCookie
  */
 export const mintCookie = (wire, name, options, mint) => {
-    const existing = options.overwrite
-        ? null
-        : wire.http?.request?.cookie(name);
+    const existing = options.overwrite ? null : wire.http?.request?.cookie(name);
     if (existing)
         return existing;
     const cache = minted.get(wire) ?? new Map();
@@ -43,7 +43,11 @@ export const mintCookie = (wire, name, options, mint) => {
     minted.set(wire, cache);
     return value;
 };
-/** Cryptographically random digits, the shape both vendor formats use. */
+/**
+ * Cryptographically random digits, the shape both vendor formats use.
+ *
+ * @example snippet: mintVendorCookie
+ */
 export const randomDigits = (length) => {
     const bytes = new Uint8Array(length);
     crypto.getRandomValues(bytes);

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

@@ -49,6 +49,11 @@ export type FunctionRuntimeMeta = {
      * everywhere else, so it is never network-callable.
      */
     scenarioStep?: boolean;
+    /**
+     * A webhook source's `receive` step, declared with `pikkuWebhookReceive`.
+     * Only its source's route runs it, so it is never RPC-callable.
+     */
+    webhookReceive?: boolean;
     /**
      * The body of a `pikkuScenario(...)`. Only ever run by `pikku scenario run`,
      * so it is held back from the app bootstrap and from every deployed unit.

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

@@ -17,12 +17,23 @@ export type CorePikkuPermissionConfig<In = any, Services extends CoreSecretlessS
 };
 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>;
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export declare const pikkuPermissionFactory: <In = any>(factory: CorePikkuPermissionFactory<In>) => CorePikkuPermissionFactory<In>;
 /**
  * Renders a human-readable approval prompt for an AI agent, in place of the
  * raw tool arguments.
  */
 export type CorePikkuApprovalDescription<In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices> = (services: Services, data: In) => Promise<string>;
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export declare const pikkuApprovalDescription: <In = any, Services extends CoreSecretlessSingletonServices = CoreSecretlessSingletonServices>(fn: CorePikkuApprovalDescription<In, Services>) => CorePikkuApprovalDescription<In, Services>;
 export type CorePikkuAuth<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = (services: Services, session: Session) => Promise<boolean> | boolean;
 export type CorePikkuAuthConfig<Services extends CoreSecretlessSingletonServices = SecretlessServices<CoreServices>, Session extends CoreUserSession = CoreUserSession> = {

package/dist/function/functions.types.js

@@ -1,9 +1,20 @@
 export const pikkuPermission = (permission) => {
     return typeof permission === 'function' ? permission : permission.func;
 };
+/**
+ * Declares a permission that takes configuration, so one check serves many
+ * call sites: `hasProfileRole({ role: 'support' })`.
+ *
+ * @example snippet: permissionFactory
+ */
 export const pikkuPermissionFactory = (factory) => {
     return factory;
 };
+/**
+ * Declares the approval prompt a function shows in place of its raw arguments.
+ *
+ * @example snippet: approvalDescription
+ */
 export const pikkuApprovalDescription = (fn) => {
     return fn;
 };

package/dist/middleware/require-origin.d.ts

@@ -16,6 +16,8 @@ export declare const isAllowedOrigin: (requestOrigin: string | null, hostOrigin:
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export declare const requireOrigin: import("./middleware.types.js").CorePikkuMiddlewareFactory<{
     /** Extra allowed origins beyond the request's own host, or a resolver for them. */

package/dist/middleware/require-origin.js

@@ -33,6 +33,8 @@ export const isAllowedOrigin = (requestOrigin, hostOrigin, configuredOrigins) =>
  * before the function body. It stops another site's page from posting to an unauthed
  * route — it is not flood control, because `Origin` is trusted from nobody but a browser.
  * A missing `Origin` is rejected too: a real browser sets one on a cross-origin-capable POST.
+ *
+ * @example snippet: requireOrigin
  */
 export const requireOrigin = pikkuMiddlewareFactory(({ origins = [] } = {}) => pikkuMiddleware({
     name: 'requireOrigin',

package/dist/permissions.d.ts

@@ -8,6 +8,11 @@ import type { PikkuRPC } from './wirings/rpc/rpc-types.js';
 export type PermissionWire = PikkuWire<any, never, false, any, PikkuRPC, never, never>;
 import type { CorePermissionGroup, CorePikkuPermission } from './function/functions.types.js';
 export declare const clearPermissionsCache: () => void;
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export declare const addGlobalPermission: (permissions: CorePermissionGroup | CorePikkuPermission[], packageName?: string | null) => CorePermissionGroup | CorePikkuPermission[];
 export declare const runPermissions: ({ funcPermissions, services, wire, data, packageName, label, }: {
     funcPermissions?: CorePermissionGroup | CorePikkuPermission[];

package/dist/permissions.js

@@ -29,6 +29,11 @@ export const clearPermissionsCache = () => {
         delete globalPermissionsCache[key];
     }
 };
+/**
+ * Applies permissions to every function, ahead of the per-function ones.
+ *
+ * @example snippet: globalPermission
+ */
 export const addGlobalPermission = (permissions, packageName = null) => {
     const state = pikkuState(packageName, 'permissions', 'global');
     if (Array.isArray(permissions)) {

package/dist/utils.d.ts

@@ -4,6 +4,13 @@ export declare const closeWireServices: (logger: Logger, wireServices: WireServi
 export declare const createWeakUID: () => string;
 export declare const isSerializable: (data: any) => boolean;
 export declare const getTagGroups: <T>(tagGroups: Record<string, T>, tag: string) => T[];
+/**
+ * `JSON.parse` of text or UTF-8 bytes, refusing anything that is not JSON with
+ * a 400 rather than a 500.
+ *
+ * @example snippet: pikkuWebhookReceive
+ */
+export declare const parseJson: <T = any>(input: string | Uint8Array) => T;
 export declare const freezeDedupe: <T>(arr?: readonly T[] | T[] | undefined) => readonly T[];
 /** Stops addon package services first, then the parent singleton services. */
 export declare const stopSingletonServices: () => Promise<void>;

package/dist/utils.js

@@ -1,4 +1,5 @@
 import { getSingletonServices, getAllPackageStates } from './pikku-state.js';
+import { BadRequestError } from './errors/errors.js';
 export const closeWireServices = async (logger, wireServices) => {
     await Promise.all(Object.values(wireServices).map(async (service) => {
         if (service?.close) {
@@ -44,6 +45,21 @@ export const getTagGroups = (tagGroups, tag) => {
     }
     return results;
 };
+/**
+ * `JSON.parse` of text or UTF-8 bytes, refusing anything that is not JSON with
+ * a 400 rather than a 500.
+ *
+ * @example snippet: pikkuWebhookReceive
+ */
+export const parseJson = (input) => {
+    const text = typeof input === 'string' ? input : new TextDecoder().decode(input);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new BadRequestError('Body is not valid JSON');
+    }
+};
 const EMPTY_ARRAY = Object.freeze([]);
 export const freezeDedupe = (arr) => {
     if (!arr || arr.length === 0)

package/dist/wirings/flag/define-feature-flags.d.ts

@@ -16,18 +16,6 @@ import type { CoreFeatureFlags } from './flag.types.js';
  * the same reason: a mid-deploy revocation is not something a code edit should
  * be able to cause.
  *
- * @example
- * ```typescript
- * defineFeatureFlags({
- *   takeInBike: {
- *     description: 'Book a bike in at the counter',
- *     anyOf: ['bikes:intake'],
- *   },
- *   aiAssistant: {
- *     description: 'The assistant panel',
- *     // no anyOf — the switch is the whole answer
- *   },
- * })
- * ```
+ * @example snippet: defineFeatureFlags
  */
 export declare const defineFeatureFlags: (_config: CoreFeatureFlags) => void;

package/dist/wirings/flag/define-feature-flags.js

@@ -15,18 +15,6 @@
  * the same reason: a mid-deploy revocation is not something a code edit should
  * be able to cause.
  *
- * @example
- * ```typescript
- * defineFeatureFlags({
- *   takeInBike: {
- *     description: 'Book a bike in at the counter',
- *     anyOf: ['bikes:intake'],
- *   },
- *   aiAssistant: {
- *     description: 'The assistant panel',
- *     // no anyOf — the switch is the whole answer
- *   },
- * })
- * ```
+ * @example snippet: defineFeatureFlags
  */
 export const defineFeatureFlags = (_config) => { };

package/dist/wirings/http/http-runner.js

@@ -215,9 +215,7 @@ const executeRoute = async (services, matchedRoute, http, options) => {
             await applyWebResponse(http.response, result);
         }
         else if (result === undefined || result === null) {
-            if (!statusSetByRoute) {
-                http?.response?.status(204);
-            }
+            // Nothing returned: the response keeps the status the function left on it.
         }
         else if (route.returnsJSON === false) {
             http?.response?.arrayBuffer(result);

package/dist/wirings/trigger/webhook-source-runner.d.ts

@@ -14,9 +14,9 @@ export declare const subscribedWebhookEvents: (source: string) => string[];
  */
 export declare const receiveWebhookSourceRequest: (sourceName: string, wire: {
     http?: PikkuHTTP;
-}) => Promise<Response | {
+}) => Promise<{
     received: number;
-}>;
+} | void>;
 /** The `pikku-incoming-webhooks` worker: runs the trigger an event was queued for. Throws so the queue retries. */
 export declare const dispatchWebhookSourceJob: (job: WebhookSourceJob) => Promise<void>;
 export type WebhookSourceOutcome = {

package/dist/wirings/trigger/webhook-source-runner.js

@@ -1,5 +1,6 @@
 import { getSingletonServices, pikkuState } from '../../pikku-state.js';
 import { addFunction, runPikkuFunc } from '../../function/function-runner.js';
+import { parseJson } from '../../utils.js';
 import { PikkuMissingMetaError, UnauthorizedError, } from '../../errors/errors.js';
 import { timingSafeStringEqual, verifyHmacSignature, verifyPublicKeySignature, } from '../../utils/hmac.js';
 import { webhookSecretCredentialName } from './webhook-source.types.js';
@@ -37,11 +38,11 @@ const getSourceMeta = (source) => {
     }
     return meta;
 };
-const runSourceStep = (singletonServices, source, funcId, data) => runPikkuFunc('trigger', source, funcId, {
+const runSourceStep = (singletonServices, source, funcId, data, wire = {}) => runPikkuFunc('trigger', source, funcId, {
     singletonServices,
     auth: false,
     data: () => data,
-    wire: {},
+    wire,
 });
 const readRequest = async (http) => {
     const request = http?.request;
@@ -134,31 +135,30 @@ export const receiveWebhookSourceRequest = async (sourceName, wire) => {
     const meta = getSourceMeta(sourceName);
     const store = singletonServices.triggerSourceStore;
     if (store && !(await store.getTriggerSource(sourceName))?.enabled) {
-        return new Response(null, { status: 404 });
+        wire.http?.response?.status(404);
+        return;
     }
     const source = pikkuState(null, 'trigger', 'webhookSources').get(sourceName);
     const request = await readRequest(wire.http);
+    // A HEAD is a provider checking the URL is live. It carries no events, so
+    // it is answered here rather than in every source's `receive`.
+    if (request.method.toLowerCase() === 'head') {
+        wire.http?.response?.status(200);
+        return;
+    }
     const verified = await verifyRequest(source, request, singletonServices);
     const result = meta.receive
-        ? await runSourceStep(singletonServices, sourceName, meta.receive, request)
+        ? await runSourceStep(singletonServices, sourceName, meta.receive, request, wire)
         : {
             events: [
                 {
                     name: '',
-                    data: request.body.length
-                        ? JSON.parse(new TextDecoder().decode(request.body))
-                        : undefined,
+                    data: request.body.length ? parseJson(request.body) : undefined,
                 },
             ],
         };
-    if ('respond' in result) {
-        const { status, body, headers } = result.respond;
-        const text = body === undefined
-            ? null
-            : typeof body === 'string'
-                ? body
-                : JSON.stringify(body);
-        return new Response(text, { status, headers });
+    if (!result) {
+        return;
     }
     if (!verified && result.events.length > 0) {
         throw new UnauthorizedError(`The ${sourceName} webhook source received events in an unsigned request`);

package/dist/wirings/trigger/webhook-source.types.d.ts

@@ -20,16 +20,12 @@ export type WebhookRequest = {
     url: string;
     query: Record<string, string>;
 };
+/**
+ * The events a request carries. A handshake returns nothing and answers
+ * through `http.response` instead, which is sent only then.
+ */
 export type WebhookReceiveResult = {
     events: TriggerEvent[];
-}
-/** A handshake, such as Slack's `url_verification`: answered directly, nothing is dispatched. */
- | {
-    respond: {
-        status: number;
-        body?: unknown;
-        headers?: Record<string, string>;
-    };
 };
 export type WebhookSourceMethod = 'post' | 'put' | 'get' | 'head';
 /** Whatever `setup` wants back on the next deploy, for providers whose endpoints cannot be found by label. */
@@ -128,7 +124,7 @@ export type CoreTriggerWebhookSource<Events extends Record<string, StandardSchem
      */
     verify?: WebhookVerify;
     /** Omitted: the JSON body is one event dispatched to the trigger named `<name>`. */
-    receive?: SourceFunction<WebhookRequest, WebhookReceiveResult>;
+    receive?: SourceFunction<WebhookRequest, WebhookReceiveResult | void>;
     check?: SourceFunction<WebhookLifecycleInput, WebhookCheckResult>;
     setup?: SourceFunction<WebhookLifecycleInput, WebhookSetupResult>;
     teardown?: SourceFunction<WebhookTeardownInput, WebhookTeardownResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.135",
+  "version": "0.12.136",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -572,6 +572,7 @@
     "isSerializable",
     "isVersionedId",
     "parseDurationString",
+    "parseJson",
     "parseVersionedId",
     "pikkuServerLifecycle",
     "stopSingletonServices"