@forumone/throughline 0.0.0-stage → 1.0.0-next.0

package/dist/integrations/jobs/healthcheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"healthcheck.js","sourceRoot":"","sources":["../../../src/integrations/jobs/healthcheck.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAEhD,OAAO,EAAE,UAAU,EAAmB,MAAM,uBAAuB,CAAA;AAInE,MAAM,gBAAgB,GAAG,cAAc,CAAA;AACvC,MAAM,oBAAoB,GAAG,KAAK,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAuC;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,gBAAgB,CAAA;IACrD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,gBAAgB,CAAA;IAEvD,OAAO,SAAS,CACd;QACE,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,aAAa;QAC/B;;;;;;;;;;UAUE;QACF,GAAG,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7B,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KACvB,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE;QACxD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,IAAI,aAAa,CAAC,CAAA;QACxF,MAAM,OAAO,GAA2D,EAAE,CAAA;QAE1E,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE;gBAC/D,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;oBAC3C,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,MAAM,EAAE,CAAA;gBACxC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO;wBACL,IAAI,EAAE,KAAK,CAAC,IAAI;wBAChB,EAAE,EAAE,KAAK;wBACT,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;qBAClE,CAAA;gBACH,CAAC;YACH,CAAC,CAAC,CAAA;YACF,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvB,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO;aACrB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,KAAK,GAAuC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;YAClE,IAAI,CAAC,CAAC,OAAO;gBAAE,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAA;YACxC,OAAO,KAAK,CAAA;QACd,CAAC,CAAC,CAAA;QAEJ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,KAAK,IAAI,EAAE;gBAC3C,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAA;YAC3B,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,MAAM,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;YAC1C,MAAM,IAAI,CAAC;gBACT,IAAI,EAAE,oBAAoB;gBAC1B,IAAI,EAAE;oBACJ,MAAM,EAAE,UAAU;oBAClB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACpC;aACF,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QAEF,MAAM,CAAC,IAAI,CAAC,sBAAsB,EAAE;YAClC,WAAW,EAAE,OAAO,CAAC,MAAM;YAC3B,QAAQ,EAAE,QAAQ,CAAC,MAAM;SAC1B,CAAC,CAAA;QAEF,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAA;IACnD,CAAC,CACF,CAAA;AACH,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,QAAmD;IACjF,sCAAsC;IACtC,OAAO,CAAC,KAAK,CACX,iBAAiB,QAAQ,CAAC,MAAM,qBAAqB,QAAQ;SAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,OAAO,IAAI,YAAY,EAAE,CAAC;SACrD,IAAI,CAAC,IAAI,CAAC,EAAE,CAChB,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CACzC,iBAAyB,OAAO;IAEhC,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,GAAG,EAAE,KAAK,EAAE,EAAE,OAAO,EAAwB,EAA8B,EAAE;YAC3E,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAA;gBAC5D,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;YACrB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;iBAClE,CAAA;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,WAAmB;IAC9D,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,GAAG,EAAE,KAAK,IAAgC,EAAE;YAC1C,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,WAAW,EAAE;oBACxC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,oBAAoB,CAAC;iBAClD,CAAC,CAAA;gBACF,IAAI,QAAQ,CAAC,EAAE;oBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;gBACpC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAA;YAC1D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;iBAClE,CAAA;YACH,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/integrations/options.d.ts

@@ -0,0 +1,54 @@
+import type { WorkflowFailureHandler } from '../jobs/workflow-types.js';
+import type { McpToolCollector } from '../mcp/collector.js';
+import type { Inngest } from 'inngest';
+import type { BaseCorePluginOptions } from '../plugin-contract/index.js';
+import type { CollectionPluginOptions } from '../plugin-contract/admin.js';
+import type { Integration } from './types.js';
+export declare const DEFAULT_INTEGRATIONS_SLUG = "integrations";
+export interface IntegrationsPluginOptions extends Omit<BaseCorePluginOptions, 'routePrefix'>, CollectionPluginOptions {
+    /**
+     * Inngest client used to register integration functions and to fire
+     * manual-sync trigger events. Give this or `emit`: integrations are an
+     * event-driven feature and there is no useful behaviour without one.
+     */
+    inngest?: Inngest;
+    /**
+     * How to send events, for a site that runs integrations as jobs rather than
+     * on Inngest: `payloadJobs().emit`. Defaults to `inngest.send`.
+     */
+    emit?: (event: {
+        name: string;
+        data: unknown;
+    }) => Promise<void>;
+    /**
+     * Called once when an integration's Inngest run has exhausted its retries,
+     * and given to every integration as `ctx.onFailure`. Default:
+     * `createTerminalFailureHandler({ payload })` from the workflows package,
+     * which records a `job-failures` row (with `jobFailuresPlugin`), logs, and
+     * reports. The webhook integration's two functions ran with none.
+     */
+    onTerminalFailure?: WorkflowFailureHandler;
+    /**
+     * Integration modules to register, in addition to the built-in webhook
+     * integration. Order matters only for tie-breaking in lists; the registry
+     * rejects duplicate ids.
+     */
+    integrations?: Integration[];
+    /** Override the Integrations collection slug. Default: 'integrations'. */
+    collectionSlug?: string;
+    /**
+     * Where to put this server's MCP tools so Payload's own MCP plugin can serve
+     * them.
+     *
+     * `createMcpToolCollector()` from `@forumone/throughline`. The host hands
+     * its array to `@payloadcms/plugin-mcp` at config time and this plugin fills
+     * it at `onInit` — which is the first moment the tools can exist, since they
+     * close over `payload`, and still before any request reads the array.
+     *
+     * Omit it and nothing changes: this server keeps its own `/mcp` endpoint,
+     * which is what lets a host move one server at a time.
+     */
+    mcpTools?: McpToolCollector;
+}
+export declare function validateOptions(options: IntegrationsPluginOptions): IntegrationsPluginOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/integrations/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/integrations/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAA;AACxE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,eAAO,MAAM,yBAAyB,iBAAiB,CAAA;AAOvD,MAAM,WAAW,yBACf,SAAQ,IAAI,CAAC,qBAAqB,EAAE,aAAa,CAAC,EAChD,uBAAuB;IACzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAA;IAC1C;;;;OAIG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAA;IAC5B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC5B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,yBAAyB,GAAG,yBAAyB,CAO7F"}

package/dist/integrations/options.js

@@ -0,0 +1,8 @@
+export const DEFAULT_INTEGRATIONS_SLUG = 'integrations';
+export function validateOptions(options) {
+    if (!options.inngest && !options.emit) {
+        throw new Error('integrationsPlugin requires an Inngest client (`options.inngest`) or a jobs adapter\'s `emit`.');
+    }
+    return options;
+}
+//# sourceMappingURL=options.js.map

package/dist/integrations/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/integrations/options.ts"],"names":[],"mappings":"AAOA,MAAM,CAAC,MAAM,yBAAyB,GAAG,cAAc,CAAA;AAqDvD,MAAM,UAAU,eAAe,CAAC,OAAkC;IAChE,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CACb,gGAAgG,CACjG,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/integrations/plugin.d.ts

@@ -0,0 +1,51 @@
+import type { CorePlugin } from '../plugin-contract/index.js';
+import { type IntegrationsPluginOptions } from './options.js';
+import { IntegrationRegistry } from './registry.js';
+import type { IntegrationContext } from './types.js';
+import { type Job } from '../jobs/types.js';
+/**
+ * Integrations server. Registers the Integrations collection — with its
+ * manual-sync endpoint and the Sync now button in its sidebar — the five-tool
+ * MCP server, and a process-local registry of integration modules. The webhook integration is registered automatically; clients
+ * extend the registry by passing additional integrations via options.
+ *
+ * Integration Inngest functions are not served here — they are exposed
+ * via `getIntegrationRegistry(payload)` so the client app's Inngest
+ * endpoint can merge them with its own functions. See
+ * `docs/integrations-wiring.md` in the repository root.
+ *
+ * The collection carries one admin component, the sidebar's Sync now button,
+ * so hosts must run `payload generate:importmap` after adding this plugin (the
+ * dev server does it automatically). A stale import map 500s the admin screen.
+ */
+export declare const integrationsPlugin: CorePlugin<IntegrationsPluginOptions>;
+/**
+ * The registry this plugin attached at init, if it did.
+ *
+ * `Fn` is the host's own Inngest function type. Naming it is what lets the host
+ * serve `createFunctions()` results without asserting them back — the registry
+ * stores integrations at `unknown` otherwise, and an `unknown[]` cannot be
+ * handed to `serve()`:
+ *
+ * ```ts
+ * const registry = getIntegrationRegistry<InngestFunction.Any>(payload)
+ * ```
+ *
+ * There is no checking behind it either way — the value comes off a symbol on
+ * the Payload instance. What the parameter buys is that the assertion happens
+ * once, here, in terms of the host's own types, rather than at every read.
+ */
+export declare function getIntegrationRegistry<Fn = unknown>(payload: unknown): IntegrationRegistry<Fn> | undefined;
+/**
+ * Every registered integration's jobs, for a site whose jobs adapter takes its
+ * jobs while the config is being built (`payloadJobs().plugin(...)`).
+ *
+ * Pass the same `integrations` as `integrationsPlugin`; the built-in webhook is
+ * included, as the plugin includes it. An integration without `createJobs`
+ * contributes nothing here and runs on Inngest only. Each job reads the
+ * integrations context from Payload when it runs, so `integrationsPlugin` must
+ * be registered too.
+ */
+export declare function integrationsJobs(options?: Pick<IntegrationsPluginOptions, 'integrations'>): Job[];
+export declare function getIntegrationContext(payload: unknown): IntegrationContext | undefined;
+//# sourceMappingURL=plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/integrations/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAK7D,OAAO,EAAE,KAAK,yBAAyB,EAA8C,MAAM,cAAc,CAAA;AACzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAKnD,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAEjE,OAAO,EAAE,KAAK,GAAG,EAAmB,MAAM,kBAAkB,CAAA;AA6B5D;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAAU,CAAC,yBAAyB,CA8IlE,CAAA;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,GAAG,OAAO,EACjD,OAAO,EAAE,OAAO,GACf,mBAAmB,CAAC,EAAE,CAAC,GAAG,SAAS,CAIrC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,IAAI,CAAC,yBAAyB,EAAE,cAAc,CAAM,GAC5D,GAAG,EAAE,CAiBP;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAEtF"}

package/dist/integrations/plugin.js

@@ -0,0 +1,215 @@
+import { getPluginRegistry } from '../plugin-contract/registry.js';
+import { createNamedLogger, defaultLogger } from '../logger/index.js';
+import { getAuditWriter } from '../audit/plugin.js';
+import { validateOptions, DEFAULT_INTEGRATIONS_SLUG } from './options.js';
+import { IntegrationRegistry } from './registry.js';
+import { createIntegrationsCollection } from './collection.js';
+import { createSyncEndpoint } from './endpoints/sync.js';
+import { createStatusWriter } from './sync/status.js';
+import { webhookIntegration } from './integrations/index.js';
+import { createTerminalFailureHandler } from '../jobs/failure-handler.js';
+import { INTEGRATIONS_TOOL_DESCRIPTORS, createGetIntegrationStatusTool, createListIntegrationsTool, createListIntegrationTypesTool, createTestIntegrationTool, createTriggerSyncTool, } from './tools/index.js';
+const PLUGIN_ID = '@forumone/throughline/integrations';
+const PLUGIN_VERSION = '0.1.0';
+/*
+A site that runs integrations as jobs has no Inngest client, but the context's
+type still promises one, so existing integrations keep compiling. Any use of it
+says what to do instead.
+*/
+const noInngest = new Proxy({}, {
+    get: () => {
+        throw new Error('This site runs integrations as jobs and has no Inngest client. Send events with ctx.emit, and give the integration createJobs.');
+    },
+});
+const REGISTRY_SYMBOL = Symbol.for('@forumone/throughline/integrations-registry');
+const CONTEXT_SYMBOL = Symbol.for('@forumone/throughline/integrations-context');
+/**
+ * Integrations server. Registers the Integrations collection — with its
+ * manual-sync endpoint and the Sync now button in its sidebar — the five-tool
+ * MCP server, and a process-local registry of integration modules. The webhook integration is registered automatically; clients
+ * extend the registry by passing additional integrations via options.
+ *
+ * Integration Inngest functions are not served here — they are exposed
+ * via `getIntegrationRegistry(payload)` so the client app's Inngest
+ * endpoint can merge them with its own functions. See
+ * `docs/integrations-wiring.md` in the repository root.
+ *
+ * The collection carries one admin component, the sidebar's Sync now button,
+ * so hosts must run `payload generate:importmap` after adding this plugin (the
+ * dev server does it automatically). A stale import map 500s the admin screen.
+ */
+export const integrationsPlugin = (rawOptions) => (incomingConfig) => {
+    if (rawOptions.enabled === false)
+        return incomingConfig;
+    const options = validateOptions(rawOptions);
+    const collectionSlug = options.collectionSlug ?? DEFAULT_INTEGRATIONS_SLUG;
+    const inngest = options.inngest;
+    // `emit` when the site gave one, otherwise Inngest; validateOptions saw to one of them.
+    const emit = options.emit ??
+        (async (event) => {
+            await inngest.send(event);
+        });
+    // What the manual-sync endpoint and tool send through.
+    const transport = { ...(inngest ? { inngest } : {}), emit };
+    const logger = createNamedLogger('integrations', options.logger ?? defaultLogger);
+    const registry = new IntegrationRegistry();
+    registry.register(webhookIntegration);
+    for (const integration of options.integrations ?? []) {
+        registry.register(integration);
+    }
+    const collection = createIntegrationsCollection({
+        slug: collectionSlug,
+        registry,
+        // The admin's path to `integration/manual-sync`, sharing
+        // `requestManualSync` with the `trigger_sync` MCP tool so the two cannot
+        // disagree about what a trigger checks or what event it sends.
+        endpoints: [createSyncEndpoint({ collectionSlug, ...transport })],
+        ...(options.admin ? { admin: options.admin } : {}),
+    });
+    /*
+    Declared here, bound at `onInit` — `mcpPlugin` generates its per-key
+    checkboxes from these names and descriptions while the config is built, and
+    denies any tool it has no checkbox for. This plugin must therefore come
+    before `mcpPlugin` in the host's array.
+    */
+    options.mcpTools?.declare(INTEGRATIONS_TOOL_DESCRIPTORS, { serverName: 'integrations' });
+    return {
+        ...incomingConfig,
+        collections: [...(incomingConfig.collections ?? []), collection],
+        onInit: async (payload) => {
+            if (incomingConfig.onInit)
+                await incomingConfig.onInit(payload);
+            const pluginRegistry = getPluginRegistry(payload);
+            pluginRegistry.requireCapability('audit-log', PLUGIN_ID);
+            const auditWriter = getAuditWriter(payload);
+            const context = {
+                inngest: options.inngest ?? noInngest,
+                emit,
+                onFailure: options.onTerminalFailure ?? createTerminalFailureHandler({ payload }),
+                integrationsCollectionSlug: collectionSlug,
+                async loadInstances(integrationId) {
+                    const result = await payload.find({
+                        collection: collectionSlug,
+                        where: {
+                            and: [
+                                { integrationType: { equals: integrationId } },
+                                { enabled: { equals: true } },
+                            ],
+                        },
+                        limit: 100,
+                    });
+                    return result.docs.map((doc) => ({
+                        id: String(doc['id']),
+                        name: String(doc['name']),
+                        config: (doc['config'] ?? {}),
+                    }));
+                },
+                updateStatus: createStatusWriter(payload, collectionSlug),
+                async recordAudit(event) {
+                    await auditWriter({
+                        actor: { type: 'system', apiKeyName: `integration:${event.integrationId}` },
+                        action: event.action,
+                        mcpServer: 'integrations',
+                        mcpTool: `integration:${event.integrationId}`,
+                        integrationId: event.instanceName,
+                        summary: event.summary,
+                        ...(event.errorMessage ? { errorMessage: event.errorMessage } : {}),
+                        success: event.action === 'integration.synced',
+                    });
+                },
+            };
+            for (const integration of registry.list()) {
+                if (options.inngest) {
+                    const fnCount = integration.createFunctions(context).length;
+                    logger.info('Integration registered', { id: integration.id, inngestFunctions: fnCount });
+                }
+                else if (integration.createJobs) {
+                    logger.info('Integration registered', { id: integration.id, runner: 'jobs' });
+                }
+                else {
+                    logger.warn('Integration has no jobs, and this site has no Inngest client, so it will not run', { id: integration.id });
+                }
+            }
+            const deps = { payload, collectionSlug };
+            const tools = [
+                createListIntegrationsTool(deps),
+                createGetIntegrationStatusTool(deps),
+                createTriggerSyncTool({ ...deps, ...transport }),
+                createTestIntegrationTool({ ...deps, registry }),
+                createListIntegrationTypesTool({ registry }),
+            ];
+            // Payload's own MCP plugin, and the only transport these tools have.
+            // `onInit` is both the earliest they can exist and still early enough
+            // that `mcpPlugin` reads the array populated.
+            options.mcpTools?.add(tools, { serverName: 'integrations', logger, audit: auditWriter });
+            Object.defineProperty(payload, REGISTRY_SYMBOL, {
+                value: registry,
+                enumerable: false,
+                writable: false,
+                configurable: false,
+            });
+            Object.defineProperty(payload, CONTEXT_SYMBOL, {
+                value: context,
+                enumerable: false,
+                writable: false,
+                configurable: false,
+            });
+            pluginRegistry.register({
+                id: PLUGIN_ID,
+                version: PLUGIN_VERSION,
+                capabilities: ['integrations', 'integration-registry'],
+            });
+            logger.info('Integrations server ready', {
+                collectionSlug,
+                integrationCount: registry.size,
+            });
+        },
+    };
+};
+/**
+ * The registry this plugin attached at init, if it did.
+ *
+ * `Fn` is the host's own Inngest function type. Naming it is what lets the host
+ * serve `createFunctions()` results without asserting them back — the registry
+ * stores integrations at `unknown` otherwise, and an `unknown[]` cannot be
+ * handed to `serve()`:
+ *
+ * ```ts
+ * const registry = getIntegrationRegistry<InngestFunction.Any>(payload)
+ * ```
+ *
+ * There is no checking behind it either way — the value comes off a symbol on
+ * the Payload instance. What the parameter buys is that the assertion happens
+ * once, here, in terms of the host's own types, rather than at every read.
+ */
+export function getIntegrationRegistry(payload) {
+    return payload[REGISTRY_SYMBOL];
+}
+/**
+ * Every registered integration's jobs, for a site whose jobs adapter takes its
+ * jobs while the config is being built (`payloadJobs().plugin(...)`).
+ *
+ * Pass the same `integrations` as `integrationsPlugin`; the built-in webhook is
+ * included, as the plugin includes it. An integration without `createJobs`
+ * contributes nothing here and runs on Inngest only. Each job reads the
+ * integrations context from Payload when it runs, so `integrationsPlugin` must
+ * be registered too.
+ */
+export function integrationsJobs(options = {}) {
+    const getContext = (job) => {
+        if (!job.payload) {
+            throw new Error('integrationsJobs: this runner gave the job no Payload instance. Use payloadJobs, or pass `payload` to inngestJobs.');
+        }
+        const context = getIntegrationContext(job.payload);
+        if (!context) {
+            throw new Error('integrationsJobs: no integrations context on Payload. Register integrationsPlugin as well.');
+        }
+        return context;
+    };
+    const integrations = [webhookIntegration, ...(options.integrations ?? [])];
+    return integrations.flatMap((integration) => integration.createJobs?.(getContext) ?? []);
+}
+export function getIntegrationContext(payload) {
+    return payload[CONTEXT_SYMBOL];
+}
+//# sourceMappingURL=plugin.js.map

package/dist/integrations/plugin.js.map

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

package/dist/integrations/registry.d.ts

@@ -0,0 +1,27 @@
+import type { Integration } from './types.js';
+/**
+ * Tiny registry keyed by integration id. Construction is per-plugin-init
+ * (not a module-level singleton) so two Payload configs in the same process
+ * don't share state. Keeps duplicate-id detection synchronous and simple.
+ *
+ * Generic in the integrations' function type, and `unknown` by default, for the
+ * same reason `Integration` is: this package never touches what
+ * `createFunctions` returns, and the host that serves them should not have to
+ * assert its way back to its own type after putting them in here.
+ *
+ * A host names it once, where it reads the registry:
+ *
+ * ```ts
+ * const registry = getIntegrationRegistry<InngestFunction.Any>(payload)
+ * const functions = registry?.list().flatMap((i) => i.createFunctions(ctx)) ?? []
+ * ```
+ */
+export declare class IntegrationRegistry<Fn = unknown> {
+    private readonly byId;
+    register(integration: Integration<Record<string, unknown>, Fn>): void;
+    get(id: string): Integration<Record<string, unknown>, Fn> | undefined;
+    list(): Integration<Record<string, unknown>, Fn>[];
+    has(id: string): boolean;
+    get size(): number;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/integrations/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/integrations/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,mBAAmB,CAAC,EAAE,GAAG,OAAO;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8D;IAEnF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI;IAOrE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,SAAS;IAIrE,IAAI,IAAI,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE;IAIlD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/integrations/registry.js

@@ -0,0 +1,39 @@
+/**
+ * Tiny registry keyed by integration id. Construction is per-plugin-init
+ * (not a module-level singleton) so two Payload configs in the same process
+ * don't share state. Keeps duplicate-id detection synchronous and simple.
+ *
+ * Generic in the integrations' function type, and `unknown` by default, for the
+ * same reason `Integration` is: this package never touches what
+ * `createFunctions` returns, and the host that serves them should not have to
+ * assert its way back to its own type after putting them in here.
+ *
+ * A host names it once, where it reads the registry:
+ *
+ * ```ts
+ * const registry = getIntegrationRegistry<InngestFunction.Any>(payload)
+ * const functions = registry?.list().flatMap((i) => i.createFunctions(ctx)) ?? []
+ * ```
+ */
+export class IntegrationRegistry {
+    byId = new Map();
+    register(integration) {
+        if (this.byId.has(integration.id)) {
+            throw new Error(`Integration "${integration.id}" is already registered`);
+        }
+        this.byId.set(integration.id, integration);
+    }
+    get(id) {
+        return this.byId.get(id);
+    }
+    list() {
+        return Array.from(this.byId.values());
+    }
+    has(id) {
+        return this.byId.has(id);
+    }
+    get size() {
+        return this.byId.size;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/integrations/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/integrations/registry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,mBAAmB;IACb,IAAI,GAAG,IAAI,GAAG,EAAoD,CAAA;IAEnF,QAAQ,CAAC,WAAqD;QAC5D,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,gBAAgB,WAAW,CAAC,EAAE,yBAAyB,CAAC,CAAA;QAC1E,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,EAAE,WAAW,CAAC,CAAA;IAC5C,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IAED,IAAI;QACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;IACvC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;IACvB,CAAC;CACF"}

package/dist/integrations/sync/manual-sync.d.ts

@@ -0,0 +1,70 @@
+import type { Inngest } from 'inngest';
+import type { Payload } from 'payload';
+/**
+ * The event every integration's manual-sync function subscribes to. Fired for
+ * *all* integrations, which is why each handler filters the payload down to
+ * its own instance rather than trusting the event.
+ */
+export declare const MANUAL_SYNC_EVENT = "integration/manual-sync";
+export interface RequestManualSyncDeps {
+    payload: Payload;
+    collectionSlug: string;
+    /** Sends the manual-sync event, unless `emit` is given. */
+    inngest?: Inngest;
+    /** Sends the manual-sync event on a site that runs integrations as jobs. */
+    emit?: (event: {
+        name: string;
+        data: unknown;
+    }) => Promise<void>;
+}
+export interface RequestManualSyncArgs {
+    /** Payload id of the instance to sync. */
+    instanceId: string;
+    /** Who asked. Recorded on the event so the run can be traced back to them. */
+    triggeredBy?: number | string | null;
+    /** Why. Carried on the event for the audit trail; not otherwise used. */
+    reason?: string | null;
+}
+/**
+ * Why a trigger was refused. Callers map these onto whatever their transport
+ * uses to say no — an error envelope for MCP, a status code for HTTP.
+ */
+export type ManualSyncRefusal = 
+/** No instance with that id. */
+'not-found'
+/** The instance exists but `enabled` is false. */
+ | 'disabled'
+/** Inngest would not take the event. */
+ | 'send-failed';
+export type RequestManualSyncResult = {
+    ok: true;
+    instanceId: string;
+    instanceName: string;
+    integrationType: string;
+    /**
+     * The instance's `lastSyncAt` at the moment the event was sent, or null
+     * if it has never run. A caller watching for the run to finish compares
+     * against this rather than against whatever it last rendered.
+     */
+    lastSyncAt: string | null;
+} | {
+    ok: false;
+    code: ManualSyncRefusal;
+    message: string;
+};
+/**
+ * Sends `integration/manual-sync` for one instance, having checked that the
+ * instance exists and is enabled.
+ *
+ * This is the single definition of what triggering a sync *means*, shared by
+ * the `trigger_sync` MCP tool and the admin endpoint behind the Sync now
+ * button. It deliberately does not check permissions: MCP and HTTP authenticate
+ * differently and each caller applies `admin`-only itself, before calling.
+ *
+ * It fires an event and returns. The sync runs in Inngest and finishes later —
+ * an `ok` result means the run was *requested*, never that it succeeded. The
+ * outcome lands on the instance's `lastSyncAt` / `lastSyncStatus` / `lastError`
+ * when the run completes.
+ */
+export declare function requestManualSync(deps: RequestManualSyncDeps, args: RequestManualSyncArgs): Promise<RequestManualSyncResult>;
+//# sourceMappingURL=manual-sync.d.ts.map

package/dist/integrations/sync/manual-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-sync.d.ts","sourceRoot":"","sources":["../../../src/integrations/sync/manual-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAEtC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAA;AAE1D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACjE;AAED,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACpC,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB;AAC3B,gCAAgC;AAC9B,WAAW;AACb,kDAAkD;GAChD,UAAU;AACZ,wCAAwC;GACtC,aAAa,CAAA;AAEjB,MAAM,MAAM,uBAAuB,GAC/B;IACE,EAAE,EAAE,IAAI,CAAA;IACR,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,GACD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CA6ElC"}

package/dist/integrations/sync/manual-sync.js

@@ -0,0 +1,91 @@
+/**
+ * The event every integration's manual-sync function subscribes to. Fired for
+ * *all* integrations, which is why each handler filters the payload down to
+ * its own instance rather than trusting the event.
+ */
+export const MANUAL_SYNC_EVENT = 'integration/manual-sync';
+/**
+ * Sends `integration/manual-sync` for one instance, having checked that the
+ * instance exists and is enabled.
+ *
+ * This is the single definition of what triggering a sync *means*, shared by
+ * the `trigger_sync` MCP tool and the admin endpoint behind the Sync now
+ * button. It deliberately does not check permissions: MCP and HTTP authenticate
+ * differently and each caller applies `admin`-only itself, before calling.
+ *
+ * It fires an event and returns. The sync runs in Inngest and finishes later —
+ * an `ok` result means the run was *requested*, never that it succeeded. The
+ * outcome lands on the instance's `lastSyncAt` / `lastSyncStatus` / `lastError`
+ * when the run completes.
+ */
+export async function requestManualSync(deps, args) {
+    let doc;
+    try {
+        doc = (await deps.payload.findByID({
+            collection: deps.collectionSlug,
+            id: args.instanceId,
+        }));
+    }
+    catch {
+        doc = null;
+    }
+    if (!doc) {
+        return {
+            ok: false,
+            code: 'not-found',
+            message: `No integration instance with id "${args.instanceId}".`,
+        };
+    }
+    const instanceName = String(doc['name']);
+    if (doc['enabled'] !== true) {
+        return {
+            ok: false,
+            code: 'disabled',
+            message: `Integration "${instanceName}" is disabled. Enable it in the admin before triggering.`,
+        };
+    }
+    const integrationType = String(doc['integrationType']);
+    try {
+        const send = deps.emit ?? ((event) => deps.inngest.send(event).then(() => undefined));
+        if (!deps.emit && !deps.inngest)
+            throw new Error('No Inngest client or emit to send the manual sync with.');
+        await send({
+            name: MANUAL_SYNC_EVENT,
+            data: {
+                integrationId: integrationType,
+                instanceId: args.instanceId,
+                triggeredBy: args.triggeredBy ?? null,
+                reason: args.reason ?? null,
+            },
+        });
+    }
+    catch (error) {
+        /*
+        A failed send used to escape as an unhandled rejection, which the MCP
+        transport turned into a generic tool error and a button would have turned
+        into nothing at all — the worst outcome, because a sync that was never
+        requested looks exactly like one that has not finished yet.
+        */
+        return {
+            ok: false,
+            code: 'send-failed',
+            message: `Could not reach Inngest to queue the sync: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // A `date` field comes back as an ISO string over REST and as a Date from
+    // the local API, and this function is called from both.
+    const rawLastSyncAt = doc['lastSyncAt'];
+    const lastSyncAt = rawLastSyncAt instanceof Date
+        ? rawLastSyncAt.toISOString()
+        : typeof rawLastSyncAt === 'string'
+            ? rawLastSyncAt
+            : null;
+    return {
+        ok: true,
+        instanceId: args.instanceId,
+        instanceName,
+        integrationType,
+        lastSyncAt,
+    };
+}
+//# sourceMappingURL=manual-sync.js.map

package/dist/integrations/sync/manual-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-sync.js","sourceRoot":"","sources":["../../../src/integrations/sync/manual-sync.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,yBAAyB,CAAA;AA+C1D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAA2B,EAC3B,IAA2B;IAE3B,IAAI,GAAmC,CAAA;IACvC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;YACjC,UAAU,EAAE,IAAI,CAAC,cAAc;YAC/B,EAAE,EAAE,IAAI,CAAC,UAAU;SACpB,CAAC,CAAmC,CAAA;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,GAAG,GAAG,IAAI,CAAA;IACZ,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,oCAAoC,IAAI,CAAC,UAAU,IAAI;SACjE,CAAA;IACH,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAA;IAExC,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,gBAAgB,YAAY,0DAA0D;SAChG,CAAA;IACH,CAAC;IAED,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAA;IAEtD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,OAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAA;QACtF,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO;YAC7B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAA;QAC5E,MAAM,IAAI,CAAC;YACT,IAAI,EAAE,iBAAiB;YACvB,IAAI,EAAE;gBACJ,aAAa,EAAE,eAAe;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU;gBAC3B,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI;gBACrC,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,IAAI;aAC5B;SACF,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf;;;;;UAKE;QACF,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,aAAa;YACnB,OAAO,EAAE,8CACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CACvD,EAAE;SACH,CAAA;IACH,CAAC;IAED,0EAA0E;IAC1E,wDAAwD;IACxD,MAAM,aAAa,GAAG,GAAG,CAAC,YAAY,CAAC,CAAA;IACvC,MAAM,UAAU,GACd,aAAa,YAAY,IAAI;QAC3B,CAAC,CAAC,aAAa,CAAC,WAAW,EAAE;QAC7B,CAAC,CAAC,OAAO,aAAa,KAAK,QAAQ;YACjC,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,IAAI,CAAA;IAEZ,OAAO;QACL,EAAE,EAAE,IAAI;QACR,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,YAAY;QACZ,eAAe;QACf,UAAU;KACX,CAAA;AACH,CAAC"}

package/dist/integrations/sync/problems.d.ts

@@ -0,0 +1,31 @@
+import type { IntegrationStatusUpdate } from '../types.js';
+/**
+ * The longest {@link problemReport} returns by default. Long enough for a
+ * handful of reasons; past that, the count says how many more there were.
+ */
+export declare const DEFAULT_PROBLEM_REPORT_LENGTH = 500;
+export interface ProblemReportOptions {
+    /** The longest the report may be, suffix included. Defaults to 500. */
+    maxLength?: number;
+}
+/**
+ * One line per thing a run left undone, joined into the single string that
+ * `lastError` and an audit `errorMessage` can share. `undefined` when the list
+ * is empty.
+ *
+ * A report longer than `maxLength` is cut at the limit and ends with the total,
+ * e.g. `… (40 problems in all)`, so a long run still says how much went wrong.
+ */
+export declare function problemReport(problems: readonly string[], options?: ProblemReportOptions): string | undefined;
+/**
+ * The `updateStatus` arguments for a run that may have left some records
+ * behind: `success` when `problems` is empty, otherwise `partial` with the
+ * capped {@link problemReport}. The status is derived from the list, so the
+ * two cannot disagree.
+ *
+ * ```ts
+ * await ctx.updateStatus(instance.id, ...statusFromProblems(problems))
+ * ```
+ */
+export declare function statusFromProblems(problems: readonly string[], options?: ProblemReportOptions): IntegrationStatusUpdate;
+//# sourceMappingURL=problems.d.ts.map