@forumone/throughline-core 0.9.1 → 0.10.0

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 export { AUDIT_ACTIONS, AUDIT_MCP_SERVERS, DEFAULT_AUDIT_SLUG, auditPlugin, createAuditCollection, createAuditWriter, getAuditWriter, } from './audit/index.js';
 export type { AuditAction, AuditActor, AuditCollectionOptions, AuditEventInput, AuditMcpServer, AuditPluginOptions, AuditWriter, AuditWriterOptions, } from './audit/index.js';
+export { EnvironmentError, assertEnvironment, checkEnvValue } from './env/index.js';
+export type { EnvValueProblem, EnvironmentCheck } from './env/index.js';
 export { createInngestClient } from './events/index.js';
 export type { CoreEvents, FrameworkEvents, InngestClientOptions } from './events/index.js';
-export { McpMetaSchema, auditContext, deniedEnvelope, createMcpToolCollector, toPayloadMcpTool, toPayloadMcpTools, withMeta, } from './mcp/index.js';
+export { MCP_API_KEYS_SLUG, McpMetaSchema, auditContext, deniedEnvelope, createMcpToolCollector, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, toPayloadMcpTool, toPayloadMcpTools, withMeta, } from './mcp/index.js';
 export type { AddToolsOptions, AuditContextFields, CreateMcpToolCollectorOptions, DeclareToolsOptions, McpMeta, McpToolCollector, McpToolDescriptor, PayloadMcpRequest, PayloadMcpTool, ToPayloadMcpToolOptions, } from './mcp/index.js';
 export { defaultLogger, createNamedLogger } from './logger/index.js';
+export { DEFAULT_JOB_FAILURES_SLUG, DEFAULT_REPORTED_HEADERS, ERROR_WEBHOOK_URL_ENV, JOB_FAILURE_KINDS, NEVER_REPORTED_HEADERS, buildHealthcheckFailureReport, buildJobFailureReport, buildRequestErrorReport, clientPrefix, createErrorReporter, createJobFailureWriter, createJobFailuresCollection, currentDeployment, describeErrorReporting, getJobFailureWriter, jobFailuresPlugin, reportError, summariseReport, } from './observability/index.js';
+export type { BuildJobFailureReportInput, BuildRequestErrorReportOptions, ErrorReport, ErrorReporter, ErrorReporterOptions, HealthcheckFailureReport, JobFailureKind, JobFailureReport, JobFailureWriter, JobFailureWriterOptions, JobFailuresCollectionOptions, JobFailuresPluginOptions, ReportDeployment, ReportableHeaders, RequestErrorReport, } from './observability/index.js';
 export { documentContentHash, formatZodIssues, sha256Hex, unwrapRelationshipId, } from './utils/index.js';
 export type { DocumentContentHashOptions } from './utils/index.js';
-export type { AuthenticatedUser, BaseCorePluginOptions, CorePlugin, Logger, McpToolContext, McpToolDefinition, PluginRegistry, PluginRegistryEntry, } from '@forumone/throughline-plugin-contract';
+export type { AuthenticatedUser, BaseCorePluginOptions, CollectionPluginOptions, CorePlugin, EnvRequirement, Logger, McpToolContext, McpToolDefinition, PluginAdminGroup, PluginAdminOptions, PluginRegistry, PluginRegistryEntry, } from '@forumone/throughline-plugin-contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,kBAAkB,GACnB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE1F,OAAO,EACL,aAAa,EACb,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,6BAA6B,EAC7B,mBAAmB,EACnB,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,oBAAoB,GACrB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAIlE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,EACV,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,uCAAuC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,kBAAkB,GACnB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACnF,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAE1F,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,6BAA6B,EAC7B,mBAAmB,EACnB,OAAO,EACP,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACX,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EACV,0BAA0B,EAC1B,8BAA8B,EAC9B,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACxB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,0BAA0B,CAAA;AAEjC,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,oBAAoB,GACrB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAIlE,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,cAAc,EACd,MAAM,EACN,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,GACpB,MAAM,uCAAuC,CAAA"}

package/dist/index.js

@@ -1,8 +1,10 @@
 // Subsystems are re-exported as they are added during C4. The aggregated
 // surface here mirrors the package's `./<subpath>` exports.
 export { AUDIT_ACTIONS, AUDIT_MCP_SERVERS, DEFAULT_AUDIT_SLUG, auditPlugin, createAuditCollection, createAuditWriter, getAuditWriter, } from './audit/index.js';
+export { EnvironmentError, assertEnvironment, checkEnvValue } from './env/index.js';
 export { createInngestClient } from './events/index.js';
-export { McpMetaSchema, auditContext, deniedEnvelope, createMcpToolCollector, toPayloadMcpTool, toPayloadMcpTools, withMeta, } from './mcp/index.js';
+export { MCP_API_KEYS_SLUG, McpMetaSchema, auditContext, deniedEnvelope, createMcpToolCollector, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, toPayloadMcpTool, toPayloadMcpTools, withMeta, } from './mcp/index.js';
 export { defaultLogger, createNamedLogger } from './logger/index.js';
+export { DEFAULT_JOB_FAILURES_SLUG, DEFAULT_REPORTED_HEADERS, ERROR_WEBHOOK_URL_ENV, JOB_FAILURE_KINDS, NEVER_REPORTED_HEADERS, buildHealthcheckFailureReport, buildJobFailureReport, buildRequestErrorReport, clientPrefix, createErrorReporter, createJobFailureWriter, createJobFailuresCollection, currentDeployment, describeErrorReporting, getJobFailureWriter, jobFailuresPlugin, reportError, summariseReport, } from './observability/index.js';
 export { documentContentHash, formatZodIssues, sha256Hex, unwrapRelationshipId, } from './utils/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4DAA4D;AAE5D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAA;AAYzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAGvD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AAcvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,oBAAoB,GACrB,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,4DAA4D;AAE5D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,cAAc,GACf,MAAM,kBAAkB,CAAA;AAYzB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAGnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAGvD,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GACT,MAAM,gBAAgB,CAAA;AAcvB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,6BAA6B,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,sBAAsB,EACtB,2BAA2B,EAC3B,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,iBAAiB,EACjB,WAAW,EACX,eAAe,GAChB,MAAM,0BAA0B,CAAA;AAmBjC,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,SAAS,EACT,oBAAoB,GACrB,MAAM,kBAAkB,CAAA"}

package/dist/mcp/api-key-access.d.ts

@@ -0,0 +1,50 @@
+import type { Access, CollectionConfig } from 'payload';
+/** The slug `@payloadcms/plugin-mcp` gives its key collection. */
+export declare const MCP_API_KEYS_SLUG = "payload-mcp-api-keys";
+/** What Payload puts on `req.user`. */
+export type AccessUser = Parameters<Access>[0]['req']['user'];
+/**
+ * True when `req.user` is an MCP key document rather than a person.
+ *
+ * Only a request authenticated by Payload's REST API-key strategy against the
+ * key collection carries this principal — which Payload 3.89.0 and later no
+ * longer register. A tool call through `/api/mcp` arrives as the key's user.
+ */
+export declare function isMcpApiKeyPrincipal(user: AccessUser | undefined): boolean;
+/**
+ * A principal a site should treat as a signed-in person.
+ *
+ * Use this wherever an access rule would otherwise say `Boolean(req.user)` —
+ * which is the rule Payload's own `defaultAccess` uses. A bearer credential
+ * presented over REST is a `req.user` and is not somebody signed in.
+ */
+export declare function isSignedIn(user: AccessUser | undefined): user is NonNullable<AccessUser>;
+/** `isSignedIn` as a Payload `Access` function. */
+export declare const signedIn: Access;
+/**
+ * An `overrideApiKeyCollection` for `mcpPlugin` that makes the key collection
+ * admin-only: read, create, update, delete and unlock all answer to `isAdmin`.
+ *
+ * `isAdmin` is the site's own rule, since only the site knows what an
+ * administrator is. Whatever it says, an MCP key principal is refused first, so
+ * a key can never manage keys.
+ *
+ * It touches `access` and nothing else, so it composes with other overrides:
+ *
+ * ```ts
+ * const keysAdminOnly = mcpApiKeyAccess(isAdmin)
+ *
+ * mcpPlugin({
+ *   mcp: { tools: mcpTools.tools },
+ *   overrideApiKeyCollection: collection => {
+ *     const hardened = keysAdminOnly(collection)
+ *     return { ...hardened, admin: { ...hardened.admin, group: 'Throughline' } }
+ *   },
+ * })
+ * ```
+ *
+ * The plugin's field-level rules on the key's `user` relationship are left as
+ * shipped: a new key is bound to whoever creates it.
+ */
+export declare function mcpApiKeyAccess(isAdmin: Access): (collection: CollectionConfig) => CollectionConfig;
+//# sourceMappingURL=api-key-access.d.ts.map

package/dist/mcp/api-key-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-access.d.ts","sourceRoot":"","sources":["../../src/mcp/api-key-access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAiCvD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,yBAAyB,CAAA;AAEvD,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,IAAI,WAAW,CAAC,UAAU,CAAC,CAExF;AAED,mDAAmD;AACnD,eAAO,MAAM,QAAQ,EAAE,MAA0C,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GACd,CAAC,UAAU,EAAE,gBAAgB,KAAK,gBAAgB,CAcpD"}

package/dist/mcp/api-key-access.js

@@ -0,0 +1,94 @@
+/*
+Who may manage MCP keys, and who counts as signed in. Issue #157.
+
+**The key collection.** `@payloadcms/plugin-mcp` brings `payload-mcp-api-keys`.
+Older releases declared it with no `access` block, so every operation fell
+through to Payload's `defaultAccess` — anybody signed in. Current ones scope each
+person to their own keys. Neither is the right rule for a collection of
+credentials: a key runs every tool as the person it is bound to, so who may mint,
+read, rotate and revoke one is an administrator's decision. `mcpApiKeyAccess`
+makes it one, through the plugin's `overrideApiKeyCollection`.
+
+**The principal.** The collection sets `auth.useAPIKey: true`. Before Payload
+3.89.0 that registered Payload's API-key strategy globally, so
+`Authorization: payload-mcp-api-keys API-Key <key>` was accepted on every REST
+route and put the *key document* on `req.user`, tagged
+`collection: 'payload-mcp-api-keys'`. It has no roles, so role checks denied it;
+`Boolean(req.user)` did not. On a site whose draft rule was "published, or
+anybody signed in", that served every draft to anyone holding a key, with no MCP
+involved.
+
+3.89.0 excludes that slug from the strategy loop, and the suite's peer floor is
+`^3.89.0` because of it. But one conditional in a dependency is not a control
+anybody here would notice losing, so `isSignedIn` refuses the key principal
+itself. Two things then have to fail for the hole to reopen.
+
+**This cannot affect `/api/mcp`.** That endpoint resolves a presented key on its
+own and runs the tool as the *user* the key points at, on the users collection,
+with that person's roles. Only the REST strategy's principal carries the key
+collection's slug, and that is the only principal refused here.
+*/
+/** The slug `@payloadcms/plugin-mcp` gives its key collection. */
+export const MCP_API_KEYS_SLUG = 'payload-mcp-api-keys';
+/**
+ * True when `req.user` is an MCP key document rather than a person.
+ *
+ * Only a request authenticated by Payload's REST API-key strategy against the
+ * key collection carries this principal — which Payload 3.89.0 and later no
+ * longer register. A tool call through `/api/mcp` arrives as the key's user.
+ */
+export function isMcpApiKeyPrincipal(user) {
+    return user?.collection === MCP_API_KEYS_SLUG;
+}
+/**
+ * A principal a site should treat as a signed-in person.
+ *
+ * Use this wherever an access rule would otherwise say `Boolean(req.user)` —
+ * which is the rule Payload's own `defaultAccess` uses. A bearer credential
+ * presented over REST is a `req.user` and is not somebody signed in.
+ */
+export function isSignedIn(user) {
+    return Boolean(user) && !isMcpApiKeyPrincipal(user);
+}
+/** `isSignedIn` as a Payload `Access` function. */
+export const signedIn = ({ req }) => isSignedIn(req.user);
+/**
+ * An `overrideApiKeyCollection` for `mcpPlugin` that makes the key collection
+ * admin-only: read, create, update, delete and unlock all answer to `isAdmin`.
+ *
+ * `isAdmin` is the site's own rule, since only the site knows what an
+ * administrator is. Whatever it says, an MCP key principal is refused first, so
+ * a key can never manage keys.
+ *
+ * It touches `access` and nothing else, so it composes with other overrides:
+ *
+ * ```ts
+ * const keysAdminOnly = mcpApiKeyAccess(isAdmin)
+ *
+ * mcpPlugin({
+ *   mcp: { tools: mcpTools.tools },
+ *   overrideApiKeyCollection: collection => {
+ *     const hardened = keysAdminOnly(collection)
+ *     return { ...hardened, admin: { ...hardened.admin, group: 'Throughline' } }
+ *   },
+ * })
+ * ```
+ *
+ * The plugin's field-level rules on the key's `user` relationship are left as
+ * shipped: a new key is bound to whoever creates it.
+ */
+export function mcpApiKeyAccess(isAdmin) {
+    const adminOnly = args => (isMcpApiKeyPrincipal(args.req.user) ? false : isAdmin(args));
+    return collection => ({
+        ...collection,
+        access: {
+            ...collection.access,
+            read: adminOnly,
+            create: adminOnly,
+            update: adminOnly,
+            delete: adminOnly,
+            unlock: adminOnly,
+        },
+    });
+}
+//# sourceMappingURL=api-key-access.js.map

package/dist/mcp/api-key-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-access.js","sourceRoot":"","sources":["../../src/mcp/api-key-access.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BE;AAEF,kEAAkE;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG,sBAAsB,CAAA;AAKvD;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA4B;IAC/D,OAAQ,IAAoD,EAAE,UAAU,KAAK,iBAAiB,CAAA;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,IAA4B;IACrD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAA;AACrD,CAAC;AAED,mDAAmD;AACnD,MAAM,CAAC,MAAM,QAAQ,GAAW,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe;IAEf,MAAM,SAAS,GAAW,IAAI,CAAC,EAAE,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IAE/F,OAAO,UAAU,CAAC,EAAE,CAAC,CAAC;QACpB,GAAG,UAAU;QACb,MAAM,EAAE;YACN,GAAG,UAAU,CAAC,MAAM;YACpB,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;SAClB;KACF,CAAC,CAAA;AACJ,CAAC"}

package/dist/mcp/index.d.ts

@@ -8,4 +8,5 @@ export { createMcpToolCollector } from './collector.js';
 export type { AddToolsOptions, CreateMcpToolCollectorOptions, DeclareToolsOptions, McpToolCollector, McpToolDescriptor, } from './collector.js';
 export { deniedEnvelope } from './envelope.js';
 export { auditServerFor, mcpServerRefusal } from './audit-server.js';
+export { MCP_API_KEYS_SLUG, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, } from './api-key-access.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACnD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACtE,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EACV,eAAe,EACf,6BAA6B,EAC7B,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACnD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACtE,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EACV,eAAe,EACf,6BAA6B,EAC7B,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,GACT,MAAM,qBAAqB,CAAA"}

package/dist/mcp/index.js

@@ -4,4 +4,5 @@ export { toPayloadMcpTool, toPayloadMcpTools } from './payload-mcp.js';
 export { createMcpToolCollector } from './collector.js';
 export { deniedEnvelope } from './envelope.js';
 export { auditServerFor, mcpServerRefusal } from './audit-server.js';
+export { MCP_API_KEYS_SLUG, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, } from './api-key-access.js';
 //# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGjD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAOtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AASvD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGjD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAOtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AASvD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,GACT,MAAM,qBAAqB,CAAA"}

package/dist/observability/collection.d.ts

@@ -0,0 +1,13 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare const DEFAULT_JOB_FAILURES_SLUG = "job-failures";
+/** What kind of thing failed. Adding a value is a schema change and needs a migration. */
+export declare const JOB_FAILURE_KINDS: readonly ["job", "healthcheck"];
+export type JobFailureKind = (typeof JOB_FAILURE_KINDS)[number];
+export interface JobFailuresCollectionOptions {
+    /** Override the collection slug. Default: `'job-failures'`. */
+    slug?: string;
+    /** Read access. Default: users with the `admin` role. */
+    readAccess?: Access;
+}
+export declare function createJobFailuresCollection(options?: JobFailuresCollectionOptions): CollectionConfig;
+//# sourceMappingURL=collection.d.ts.map

package/dist/observability/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/observability/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAgBvD,eAAO,MAAM,yBAAyB,iBAAiB,CAAA;AAEvD,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,iCAAkC,CAAA;AAChE,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/D,MAAM,WAAW,4BAA4B;IAC3C,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAOD,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,4BAAiC,GACzC,gBAAgB,CAuDlB"}

package/dist/observability/collection.js

@@ -0,0 +1,76 @@
+/*
+Where a background job's failure is recorded.
+
+Deliberately not the audit log. `audit-events` records who did what through
+an MCP tool — `mcpServer` and `mcpTool` are `NOT NULL`, and every row answers
+"which tool did this". A cron that ran out of retries is not an action anybody
+took; it is an operational fact, with its own fields (a run id, a triggering
+event) and its own lifetime (worth keeping for weeks, not forever). Giving it
+a fake MCP server name would make that column mean nothing.
+
+Read-only from outside the writer, like the audit log: the writer uses the
+Local API, which bypasses these access rules.
+*/
+export const DEFAULT_JOB_FAILURES_SLUG = 'job-failures';
+/** What kind of thing failed. Adding a value is a schema change and needs a migration. */
+export const JOB_FAILURE_KINDS = ['job', 'healthcheck'];
+const adminOnly = ({ req }) => {
+    const roles = req.user?.['roles'] ?? [];
+    return roles.includes('admin');
+};
+export function createJobFailuresCollection(options = {}) {
+    return {
+        slug: options.slug ?? DEFAULT_JOB_FAILURES_SLUG,
+        admin: {
+            useAsTitle: 'summary',
+            defaultColumns: ['createdAt', 'kind', 'source', 'message'],
+            description: 'Background jobs that ran out of retries, and healthchecks that failed. Read-only; written by the failure handlers.',
+        },
+        access: {
+            read: options.readAccess ?? adminOnly,
+            create: () => false,
+            update: () => false,
+            delete: () => false,
+        },
+        fields: [
+            {
+                name: 'createdAt',
+                type: 'date',
+                required: true,
+                defaultValue: () => new Date().toISOString(),
+                admin: { position: 'sidebar', readOnly: true },
+            },
+            {
+                name: 'kind',
+                type: 'select',
+                required: true,
+                options: JOB_FAILURE_KINDS.map((value) => ({ label: value, value })),
+            },
+            {
+                name: 'source',
+                type: 'text',
+                required: true,
+                admin: { description: 'The function or check that failed, e.g. an Inngest function id.' },
+            },
+            { name: 'summary', type: 'text', required: true },
+            { name: 'message', type: 'textarea', required: true },
+            { name: 'errorName', type: 'text' },
+            {
+                name: 'runId',
+                type: 'text',
+                admin: { description: "The run's id in the job runner, for finding it in its dashboard." },
+            },
+            { name: 'triggerEvent', type: 'text' },
+            {
+                name: 'details',
+                type: 'json',
+                admin: { description: 'For a healthcheck: every failed check and what it said.' },
+            },
+            { name: 'environment', type: 'text' },
+            { name: 'commit', type: 'text' },
+        ],
+        indexes: [{ fields: ['createdAt'] }, { fields: ['source', 'createdAt'] }],
+        timestamps: false,
+    };
+}
+//# sourceMappingURL=collection.js.map

package/dist/observability/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../../src/observability/collection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;EAYE;AAEF,MAAM,CAAC,MAAM,yBAAyB,GAAG,cAAc,CAAA;AAEvD,0FAA0F;AAC1F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,aAAa,CAAU,CAAA;AAUhE,MAAM,SAAS,GAAW,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE;IACpC,MAAM,KAAK,GAAI,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAA0B,IAAI,EAAE,CAAA;IACjE,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AAChC,CAAC,CAAA;AAED,MAAM,UAAU,2BAA2B,CACzC,UAAwC,EAAE;IAE1C,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,yBAAyB;QAC/C,KAAK,EAAE;YACL,UAAU,EAAE,SAAS;YACrB,cAAc,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;YAC1D,WAAW,EACT,oHAAoH;SACvH;QACD,MAAM,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;YACrC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;YACnB,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;YACnB,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;SACpB;QACD,MAAM,EAAE;YACN;gBACE,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,IAAI;gBACd,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBAC5C,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE;aAC/C;YACD;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,iBAAiB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;aACrE;YACD;gBACE,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,MAAM;gBACZ,QAAQ,EAAE,IAAI;gBACd,KAAK,EAAE,EAAE,WAAW,EAAE,iEAAiE,EAAE;aAC1F;YACD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;YACjD,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE;YACrD,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE;YACnC;gBACE,IAAI,EAAE,OAAO;gBACb,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,EAAE,WAAW,EAAE,kEAAkE,EAAE;aAC3F;YACD,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE;YACtC;gBACE,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,EAAE,WAAW,EAAE,yDAAyD,EAAE;aAClF;YACD,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE;YACrC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE;SACjC;QACD,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC;QACzE,UAAU,EAAE,KAAK;KAClB,CAAA;AACH,CAAC"}

package/dist/observability/index.d.ts

@@ -0,0 +1,9 @@
+export { DEFAULT_REPORTED_HEADERS, ERROR_WEBHOOK_URL_ENV, NEVER_REPORTED_HEADERS, buildHealthcheckFailureReport, buildJobFailureReport, buildRequestErrorReport, clientPrefix, createErrorReporter, currentDeployment, describeErrorReporting, reportError, summariseReport, } from './report.js';
+export type { BuildJobFailureReportInput, BuildRequestErrorReportOptions, ErrorReport, ErrorReporter, ErrorReporterOptions, HealthcheckFailureReport, JobFailureReport, ReportDeployment, ReportableHeaders, RequestErrorReport, } from './report.js';
+export { DEFAULT_JOB_FAILURES_SLUG, JOB_FAILURE_KINDS, createJobFailuresCollection, } from './collection.js';
+export type { JobFailureKind, JobFailuresCollectionOptions } from './collection.js';
+export { createJobFailureWriter } from './writer.js';
+export type { JobFailureWriter, JobFailureWriterOptions } from './writer.js';
+export { getJobFailureWriter, jobFailuresPlugin } from './plugin.js';
+export type { JobFailuresPluginOptions } from './plugin.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,6BAA6B,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,eAAe,GAChB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,0BAA0B,EAC1B,8BAA8B,EAC9B,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AAEpB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,cAAc,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAA;AAEnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,YAAY,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAE5E,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpE,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA"}

package/dist/observability/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_REPORTED_HEADERS, ERROR_WEBHOOK_URL_ENV, NEVER_REPORTED_HEADERS, buildHealthcheckFailureReport, buildJobFailureReport, buildRequestErrorReport, clientPrefix, createErrorReporter, currentDeployment, describeErrorReporting, reportError, summariseReport, } from './report.js';
+export { DEFAULT_JOB_FAILURES_SLUG, JOB_FAILURE_KINDS, createJobFailuresCollection, } from './collection.js';
+export { createJobFailureWriter } from './writer.js';
+export { getJobFailureWriter, jobFailuresPlugin } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EACtB,6BAA6B,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,eAAe,GAChB,MAAM,aAAa,CAAA;AAcpB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAGpD,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA"}

package/dist/observability/plugin.d.ts

@@ -0,0 +1,21 @@
+import { type BaseCorePluginOptions, type CorePlugin } from '@forumone/throughline-plugin-contract';
+import { type JobFailuresCollectionOptions } from './collection.js';
+import { type JobFailureWriter } from './writer.js';
+export interface JobFailuresPluginOptions extends BaseCorePluginOptions, JobFailuresCollectionOptions {
+}
+/**
+ * Adds the `job-failures` collection and attaches its writer to the Payload
+ * instance, where `getJobFailureWriter` — and the workflows package's failure
+ * handlers — find it.
+ */
+export declare const jobFailuresPlugin: CorePlugin<JobFailuresPluginOptions>;
+/**
+ * The writer `jobFailuresPlugin` attached, or `undefined` when the plugin is
+ * not registered.
+ *
+ * Unlike `getAuditWriter` this does not throw: it is called from failure
+ * handlers, which fall back to logging and reporting when there is nowhere
+ * to write.
+ */
+export declare function getJobFailureWriter(payload: object): JobFailureWriter | undefined;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/observability/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/observability/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EAEhB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAA+B,KAAK,4BAA4B,EAAE,MAAM,iBAAiB,CAAA;AAChG,OAAO,EAA0B,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAO3E,MAAM,WAAW,wBACf,SAAQ,qBAAqB,EAAE,4BAA4B;CAAG;AAEhE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,wBAAwB,CA4BhE,CAAA;AAEH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAEjF"}

package/dist/observability/plugin.js

@@ -0,0 +1,51 @@
+import { getPluginRegistry, } from '@forumone/throughline-plugin-contract';
+import { createJobFailuresCollection } from './collection.js';
+import { createJobFailureWriter } from './writer.js';
+import { defaultLogger } from '../logger/index.js';
+const PLUGIN_ID = '@forumone/throughline-core/observability';
+const PLUGIN_VERSION = '0.1.0';
+const WRITER_SYMBOL = Symbol.for('@forumone/throughline/job-failure-writer');
+/**
+ * Adds the `job-failures` collection and attaches its writer to the Payload
+ * instance, where `getJobFailureWriter` — and the workflows package's failure
+ * handlers — find it.
+ */
+export const jobFailuresPlugin = (options) => (incomingConfig) => {
+    if (options.enabled === false)
+        return incomingConfig;
+    return {
+        ...incomingConfig,
+        collections: [...(incomingConfig.collections ?? []), createJobFailuresCollection(options)],
+        onInit: async (payload) => {
+            if (incomingConfig.onInit)
+                await incomingConfig.onInit(payload);
+            Object.defineProperty(payload, WRITER_SYMBOL, {
+                value: createJobFailureWriter({
+                    payload,
+                    collectionSlug: options.slug,
+                    logger: options.logger ?? defaultLogger,
+                }),
+                enumerable: false,
+                writable: false,
+                configurable: false,
+            });
+            getPluginRegistry(payload).register({
+                id: PLUGIN_ID,
+                version: PLUGIN_VERSION,
+                capabilities: ['job-failures'],
+            });
+        },
+    };
+};
+/**
+ * The writer `jobFailuresPlugin` attached, or `undefined` when the plugin is
+ * not registered.
+ *
+ * Unlike `getAuditWriter` this does not throw: it is called from failure
+ * handlers, which fall back to logging and reporting when there is nowhere
+ * to write.
+ */
+export function getJobFailureWriter(payload) {
+    return payload[WRITER_SYMBOL];
+}
+//# sourceMappingURL=plugin.js.map

package/dist/observability/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/observability/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,iBAAiB,GAClB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,2BAA2B,EAAqC,MAAM,iBAAiB,CAAA;AAChG,OAAO,EAAE,sBAAsB,EAAyB,MAAM,aAAa,CAAA;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,MAAM,SAAS,GAAG,0CAA0C,CAAA;AAC5D,MAAM,cAAc,GAAG,OAAO,CAAA;AAC9B,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAA;AAK5E;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAC5B,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE,EAAE;IAC9B,IAAI,OAAO,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,cAAc,CAAA;IAEpD,OAAO;QACL,GAAG,cAAc;QACjB,WAAW,EAAE,CAAC,GAAG,CAAC,cAAc,CAAC,WAAW,IAAI,EAAE,CAAC,EAAE,2BAA2B,CAAC,OAAO,CAAC,CAAC;QAC1F,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACxB,IAAI,cAAc,CAAC,MAAM;gBAAE,MAAM,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YAE/D,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE;gBAC5C,KAAK,EAAE,sBAAsB,CAAC;oBAC5B,OAAO;oBACP,cAAc,EAAE,OAAO,CAAC,IAAI;oBAC5B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,aAAa;iBACxC,CAAC;gBACF,UAAU,EAAE,KAAK;gBACjB,QAAQ,EAAE,KAAK;gBACf,YAAY,EAAE,KAAK;aACpB,CAAC,CAAA;YAEF,iBAAiB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;gBAClC,EAAE,EAAE,SAAS;gBACb,OAAO,EAAE,cAAc;gBACvB,YAAY,EAAE,CAAC,cAAc,CAAC;aAC/B,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC,CAAA;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAQ,OAAmC,CAAC,aAAa,CAAiC,CAAA;AAC5F,CAAC"}

package/dist/observability/report.d.ts

@@ -0,0 +1,175 @@
+import type { Logger } from '@forumone/throughline-plugin-contract';
+/** Request headers copied into a report unless the caller names its own list. */
+export declare const DEFAULT_REPORTED_HEADERS: readonly string[];
+/**
+ * Headers that are never copied, even when a caller lists them. Each one is,
+ * or routinely carries, a credential. `x-forwarded-for` is here too: the whole
+ * address is personal data, and a report carries only its prefix.
+ */
+export declare const NEVER_REPORTED_HEADERS: readonly string[];
+/** The environment variable the default reporter reads. */
+export declare const ERROR_WEBHOOK_URL_ENV = "ERROR_WEBHOOK_URL";
+/** Which deployment produced a report, so it is attributable after a rollback. */
+export interface ReportDeployment {
+    environment?: string;
+    commit?: string;
+}
+/** An unhandled error in a request, as `instrumentation.ts` sees one. */
+export interface RequestErrorReport {
+    kind: 'request';
+    /** ISO 8601, so a report is orderable without trusting the receiver's clock. */
+    at: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    /** React's error digest — the only handle on a minified Server Component error. */
+    digest?: string;
+    request: {
+        path: string;
+        method: string;
+        /** The allowlisted headers that were present, lower-cased. */
+        headers: Record<string, string>;
+        /** The client address reduced to a /16 (IPv4) or /64 (IPv6). */
+        clientPrefix?: string;
+    };
+    context: {
+        routePath?: string;
+        routeType?: string;
+        renderSource?: string;
+        revalidateReason?: string;
+    };
+    deployment: ReportDeployment;
+}
+/** A background job that ran out of retries. */
+export interface JobFailureReport {
+    kind: 'job';
+    at: string;
+    /** The function that failed, e.g. an Inngest function id. `'unknown'` if nothing named it. */
+    functionId: string;
+    /** The run's id — the handle for finding it in the job runner's dashboard. */
+    runId?: string;
+    /** The event that triggered the run, so a failure is traceable to a cause. */
+    triggerEvent?: string;
+    message: string;
+    name?: string;
+    stack?: string;
+    deployment: ReportDeployment;
+}
+/** A healthcheck run in which at least one check failed. */
+export interface HealthcheckFailureReport {
+    kind: 'healthcheck';
+    at: string;
+    functionId: string;
+    failed: Array<{
+        name: string;
+        details?: string;
+    }>;
+    deployment: ReportDeployment;
+}
+export type ErrorReport = RequestErrorReport | JobFailureReport | HealthcheckFailureReport;
+/** Request headers as Next hands them over, or a Fetch `Headers`. */
+export type ReportableHeaders = Record<string, string | string[] | undefined> | {
+    get(name: string): string | null;
+};
+export interface BuildRequestErrorReportOptions {
+    /** Headers to copy. Default: {@link DEFAULT_REPORTED_HEADERS}. {@link NEVER_REPORTED_HEADERS} are dropped regardless. */
+    headers?: readonly string[];
+    /** Default: read from the environment — see {@link currentDeployment}. */
+    deployment?: ReportDeployment;
+    now?: Date;
+}
+/**
+ * The deployment a report came from, read from the environment.
+ *
+ * `VERCEL_ENV` before `NODE_ENV`, because on Vercel a preview deployment is
+ * `NODE_ENV=production` too, and "production or somebody's branch" is the
+ * first question about an alert. Off Vercel, `NODE_ENV` is what there is.
+ */
+export declare function currentDeployment(env?: NodeJS.ProcessEnv): ReportDeployment;
+/**
+ * An IPv4 or IPv6 address reduced to a prefix: enough to tell one host's burst
+ * from many readers hitting the same fault, and not enough to identify anyone.
+ * `x-forwarded-for` may carry a list; only the first entry is the client.
+ */
+export declare function clientPrefix(forwardedFor: string | undefined): string | undefined;
+/**
+ * Build a report for an error captured during a request. Pure, so the
+ * redaction is testable without a server.
+ *
+ * `error` is `unknown` because Next types it that way and means it: the value
+ * reaching `onRequestError` may have been processed by React rather than being
+ * the instance that was thrown, which is why `digest` is read separately.
+ */
+export declare function buildRequestErrorReport(error: unknown, request: {
+    path: string;
+    method: string;
+    headers: ReportableHeaders;
+}, context?: object, options?: BuildRequestErrorReportOptions): RequestErrorReport;
+export interface BuildJobFailureReportInput {
+    /** The failing function. Omitted or empty is reported as `'unknown'` rather than dropped. */
+    functionId?: string | undefined;
+    runId?: string | undefined;
+    triggerEvent?: string | undefined;
+    error: unknown;
+}
+/**
+ * Build a report for a job that ran out of retries.
+ *
+ * The stack is included: this goes to a webhook the team owns, where a stack
+ * is the most useful field in it. The job-failures collection, which admins
+ * read through the CMS, stores the message and not the stack.
+ */
+export declare function buildJobFailureReport(input: BuildJobFailureReportInput, options?: {
+    deployment?: ReportDeployment;
+    now?: Date;
+}): JobFailureReport;
+/** Build a report for a healthcheck run with failing checks. */
+export declare function buildHealthcheckFailureReport(failures: ReadonlyArray<{
+    name: string;
+    details?: string | undefined;
+}>, options?: {
+    functionId?: string;
+    deployment?: ReportDeployment;
+    now?: Date;
+}): HealthcheckFailureReport;
+/**
+ * One line describing a report, for a receiver that renders rather than
+ * indexes. Reads the report structurally, so a site's own report shapes get a
+ * sensible line too.
+ */
+export declare function summariseReport(report: unknown): string;
+/**
+ * Whether reports go anywhere, as a sentence for a boot-time log line. A
+ * sentence rather than a boolean because "off because this is a laptop" and
+ * "off because somebody forgot in production" look identical otherwise.
+ */
+export declare function describeErrorReporting(url?: string | undefined): string;
+export interface ErrorReporterOptions {
+    /**
+     * Where to POST. Default: `process.env.ERROR_WEBHOOK_URL`, read on every
+     * call so a reporter built before the environment loads still finds it.
+     * Unset or empty means reports are not delivered.
+     */
+    url?: string | undefined;
+    /** Extra headers sent *to the webhook*, e.g. an `authorization` the receiver expects. */
+    webhookHeaders?: Record<string, string>;
+    /** Abort the POST after this long. Default: 3000ms — shorter than any function timeout. */
+    timeoutMs?: number;
+    /** Where a failed delivery is logged. Default: the console logger. */
+    logger?: Logger;
+    /** Injected for tests. Default: the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** Posts a report. Never throws, never rejects. */
+export type ErrorReporter = (report: unknown) => Promise<void>;
+/**
+ * A reporter that POSTs each report as JSON, with a `text` summary added.
+ *
+ * A delivery that fails — a refused connection, a timeout, a non-2xx — is
+ * logged as a warning and otherwise swallowed. It is never rethrown: see the
+ * note at the top of this file.
+ */
+export declare function createErrorReporter(options?: ErrorReporterOptions): ErrorReporter;
+/** The default reporter: `ERROR_WEBHOOK_URL`, a 3s timeout, the console logger. */
+export declare const reportError: ErrorReporter;
+//# sourceMappingURL=report.d.ts.map

package/dist/observability/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/observability/report.ts"],"names":[],"mappings":"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"}