@forumone/throughline-integrations 0.0.1 → 0.2.1

package/dist/tools/list-integration-types.d.ts

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import type { McpToolDefinition } from '@forumone/throughline-plugin-contract';
+import type { IntegrationRegistry } from '../registry.js';
+export interface ListIntegrationTypesDeps {
+    registry: IntegrationRegistry;
+}
+declare const inputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
+export declare function createListIntegrationTypesTool(deps: ListIntegrationTypesDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=list-integration-types.d.ts.map

package/dist/tools/list-integration-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-integration-types.d.ts","sourceRoot":"","sources":["../../src/tools/list-integration-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAEzD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAED,QAAA,MAAM,WAAW,iDAAwB,CAAA;AAEzC,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,wBAAwB,GAC7B,iBAAiB,CAAC,OAAO,WAAW,CAAC,CAmBvC"}

package/dist/tools/list-integration-types.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+const inputSchema = z.object({}).strict();
+export function createListIntegrationTypesTool(deps) {
+    return {
+        name: 'list_integration_types',
+        description: 'Lists the integration plugins available in this deployment. Use when answering "what kinds of integrations are supported here?" or before suggesting that someone add a new instance.',
+        inputSchema,
+        handler: async () => {
+            return {
+                types: deps.registry.list().map((integration) => ({
+                    id: integration.id,
+                    name: integration.name,
+                    description: integration.description,
+                    category: integration.category,
+                    subscribesTo: integration.subscribes.map((s) => s.event),
+                    hasHealthcheck: typeof integration.healthcheck === 'function',
+                })),
+            };
+        },
+    };
+}
+//# sourceMappingURL=list-integration-types.js.map

package/dist/tools/list-integration-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-integration-types.js","sourceRoot":"","sources":["../../src/tools/list-integration-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAQvB,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;AAEzC,MAAM,UAAU,8BAA8B,CAC5C,IAA8B;IAE9B,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,uLAAuL;QACzL,WAAW;QACX,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,OAAO;gBACL,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;oBAChD,EAAE,EAAE,WAAW,CAAC,EAAE;oBAClB,IAAI,EAAE,WAAW,CAAC,IAAI;oBACtB,WAAW,EAAE,WAAW,CAAC,WAAW;oBACpC,QAAQ,EAAE,WAAW,CAAC,QAAQ;oBAC9B,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;oBACxD,cAAc,EAAE,OAAO,WAAW,CAAC,WAAW,KAAK,UAAU;iBAC9D,CAAC,CAAC;aACJ,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tools/list-integrations.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '@forumone/throughline-plugin-contract';
+export interface ListIntegrationsDeps {
+    payload: Payload;
+    collectionSlug: string;
+}
+declare const inputSchema: z.ZodObject<{
+    integrationType: z.ZodOptional<z.ZodString>;
+    onlyEnabled: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    integrationType?: string | undefined;
+    onlyEnabled?: boolean | undefined;
+}, {
+    integrationType?: string | undefined;
+    onlyEnabled?: boolean | undefined;
+}>;
+export declare function createListIntegrationsTool(deps: ListIntegrationsDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=list-integrations.d.ts.map

package/dist/tools/list-integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-integrations.d.ts","sourceRoot":"","sources":["../../src/tools/list-integrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,SAAS,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAG9E,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,QAAA,MAAM,WAAW;;;;;;;;;EASf,CAAA;AAEF,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,oBAAoB,GACzB,iBAAiB,CAAC,OAAO,WAAW,CAAC,CAqCvC"}

package/dist/tools/list-integrations.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { deniedEnvelope, isIntegrationsReader } from './access.js';
+const inputSchema = z.object({
+    integrationType: z
+        .string()
+        .optional()
+        .describe('Filter to a specific integration type (e.g. "webhook").'),
+    onlyEnabled: z
+        .boolean()
+        .optional()
+        .describe('If true, exclude disabled instances. Default: false.'),
+});
+export function createListIntegrationsTool(deps) {
+    return {
+        name: 'list_integrations',
+        description: 'Lists configured integration instances and their last-sync status. Use to answer "what connections are set up?" or "is the webhook to Slack still working?". Read-only.',
+        inputSchema,
+        handler: async (input, ctx) => {
+            if (!isIntegrationsReader(ctx)) {
+                return deniedEnvelope('Only admins and editors can list integrations.');
+            }
+            const conditions = [];
+            if (input.integrationType)
+                conditions.push({ integrationType: { equals: input.integrationType } });
+            if (input.onlyEnabled)
+                conditions.push({ enabled: { equals: true } });
+            const result = await deps.payload.find({
+                collection: deps.collectionSlug,
+                ...(conditions.length > 0 ? { where: { and: conditions } } : {}),
+                sort: 'name',
+                limit: 100,
+            });
+            const docs = result.docs;
+            return {
+                total: result.totalDocs,
+                integrations: docs.map((doc) => ({
+                    id: String(doc['id']),
+                    name: String(doc['name']),
+                    type: String(doc['integrationType']),
+                    enabled: doc['enabled'] === true,
+                    lastSyncAt: typeof doc['lastSyncAt'] === 'string' ? doc['lastSyncAt'] : null,
+                    lastSyncStatus: typeof doc['lastSyncStatus'] === 'string' ? doc['lastSyncStatus'] : 'never-run',
+                    lastError: typeof doc['lastError'] === 'string' ? doc['lastError'] : undefined,
+                })),
+            };
+        },
+    };
+}
+//# sourceMappingURL=list-integrations.js.map

package/dist/tools/list-integrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-integrations.js","sourceRoot":"","sources":["../../src/tools/list-integrations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAOlE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,yDAAyD,CAAC;IACtE,WAAW,EAAE,CAAC;SACX,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CAAC,sDAAsD,CAAC;CACpE,CAAC,CAAA;AAEF,MAAM,UAAU,0BAA0B,CACxC,IAA0B;IAE1B,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,WAAW,EACT,yKAAyK;QAC3K,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,OAAO,cAAc,CAAC,gDAAgD,CAAC,CAAA;YACzE,CAAC;YAED,MAAM,UAAU,GAAY,EAAE,CAAA;YAC9B,IAAI,KAAK,CAAC,eAAe;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,eAAe,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,eAAe,EAAE,EAAE,CAAC,CAAA;YAClG,IAAI,KAAK,CAAC,WAAW;gBAAE,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;YAErE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;gBACrC,UAAU,EAAE,IAAI,CAAC,cAAc;gBAC/B,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,GAAG;aACX,CAAC,CAAA;YAEF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAsC,CAAA;YAC1D,OAAO;gBACL,KAAK,EAAE,MAAM,CAAC,SAAS;gBACvB,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;oBAC/B,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;oBACrB,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBACzB,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;oBACpC,OAAO,EAAE,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI;oBAChC,UAAU,EAAE,OAAO,GAAG,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,IAAI;oBAC5E,cAAc,EAAE,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,WAAW;oBAC/F,SAAS,EAAE,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;iBAC/E,CAAC,CAAC;aACJ,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tools/test-integration.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '@forumone/throughline-plugin-contract';
+import type { IntegrationRegistry } from '../registry.js';
+export interface TestIntegrationDeps {
+    payload: Payload;
+    collectionSlug: string;
+    registry: IntegrationRegistry;
+}
+declare const inputSchema: z.ZodObject<{
+    integrationId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    integrationId: string;
+}, {
+    integrationId: string;
+}>;
+export declare function createTestIntegrationTool(deps: TestIntegrationDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=test-integration.d.ts.map

package/dist/tools/test-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-integration.d.ts","sourceRoot":"","sources":["../../src/tools/test-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAC9E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAGzD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,mBAAmB,CAAA;CAC9B;AAED,QAAA,MAAM,WAAW;;;;;;EAEf,CAAA;AAEF,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,mBAAmB,GACxB,iBAAiB,CAAC,OAAO,WAAW,CAAC,CAgDvC"}

package/dist/tools/test-integration.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { deniedEnvelope, isIntegrationsReader } from './access.js';
+const inputSchema = z.object({
+    integrationId: z.string().describe('The instance ID to test.'),
+});
+export function createTestIntegrationTool(deps) {
+    return {
+        name: 'test_integration',
+        description: "Calls the integration's healthcheck. Use to answer 'is the integration reachable / configured correctly?'. Doesn't fire any system events; the test is local to the integration's healthcheck.",
+        inputSchema,
+        handler: async (input, ctx) => {
+            if (!isIntegrationsReader(ctx)) {
+                return deniedEnvelope('Only admins and editors can test integrations.');
+            }
+            let doc = null;
+            try {
+                doc = (await deps.payload.findByID({
+                    collection: deps.collectionSlug,
+                    id: input.integrationId,
+                }));
+            }
+            catch {
+                doc = null;
+            }
+            if (!doc)
+                return { error: `No integration instance with id "${input.integrationId}".` };
+            const integrationType = String(doc['integrationType']);
+            const integration = deps.registry.get(integrationType);
+            if (!integration) {
+                return { error: `Unknown integration type "${integrationType}".` };
+            }
+            if (!integration.healthcheck) {
+                return {
+                    ok: null,
+                    message: `${integration.name} does not implement a healthcheck.`,
+                };
+            }
+            const config = (doc['config'] ?? {});
+            const result = await integration.healthcheck(config);
+            return {
+                instanceId: input.integrationId,
+                instanceName: String(doc['name']),
+                type: integrationType,
+                healthy: result.ok,
+                details: result.details ?? null,
+            };
+        },
+    };
+}
+//# sourceMappingURL=test-integration.js.map

package/dist/tools/test-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-integration.js","sourceRoot":"","sources":["../../src/tools/test-integration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAQlE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;CAC/D,CAAC,CAAA;AAEF,MAAM,UAAU,yBAAyB,CACvC,IAAyB;IAEzB,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,gMAAgM;QAClM,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC/B,OAAO,cAAc,CAAC,gDAAgD,CAAC,CAAA;YACzE,CAAC;YAED,IAAI,GAAG,GAAmC,IAAI,CAAA;YAC9C,IAAI,CAAC;gBACH,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;oBACjC,UAAU,EAAE,IAAI,CAAC,cAAc;oBAC/B,EAAE,EAAE,KAAK,CAAC,aAAa;iBACxB,CAAC,CAAmC,CAAA;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,GAAG,IAAI,CAAA;YACZ,CAAC;YAED,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,KAAK,EAAE,oCAAoC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAA;YAEvF,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAA;YACtD,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;YACtD,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,OAAO,EAAE,KAAK,EAAE,6BAA6B,eAAe,IAAI,EAAE,CAAA;YACpE,CAAC;YAED,IAAI,CAAC,WAAW,CAAC,WAAW,EAAE,CAAC;gBAC7B,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,OAAO,EAAE,GAAG,WAAW,CAAC,IAAI,oCAAoC;iBACjE,CAAA;YACH,CAAC;YAED,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAA4B,CAAA;YAC/D,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;YAEpD,OAAO;gBACL,UAAU,EAAE,KAAK,CAAC,aAAa;gBAC/B,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjC,IAAI,EAAE,eAAe;gBACrB,OAAO,EAAE,MAAM,CAAC,EAAE;gBAClB,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;aAChC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/tools/trigger-sync.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { Inngest } from 'inngest';
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '@forumone/throughline-plugin-contract';
+export interface TriggerSyncDeps {
+    payload: Payload;
+    collectionSlug: string;
+    inngest: Inngest;
+}
+declare const inputSchema: z.ZodObject<{
+    integrationId: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    integrationId: string;
+    reason?: string | undefined;
+}, {
+    integrationId: string;
+    reason?: string | undefined;
+}>;
+export declare function createTriggerSyncTool(deps: TriggerSyncDeps): McpToolDefinition<typeof inputSchema>;
+export {};
+//# sourceMappingURL=trigger-sync.d.ts.map

package/dist/tools/trigger-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-sync.d.ts","sourceRoot":"","sources":["../../src/tools/trigger-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAA;AAG9E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,QAAA,MAAM,WAAW;;;;;;;;;EAQf,CAAA;AAEF,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,GACpB,iBAAiB,CAAC,OAAO,WAAW,CAAC,CAmDvC"}

package/dist/tools/trigger-sync.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { deniedEnvelope, isIntegrationsAdmin } from './access.js';
+const inputSchema = z.object({
+    integrationId: z
+        .string()
+        .describe('The instance ID to sync. Use list_integrations to find it.'),
+    reason: z
+        .string()
+        .optional()
+        .describe('Why the sync was triggered. Recorded for the audit trail.'),
+});
+export function createTriggerSyncTool(deps) {
+    return {
+        name: 'trigger_sync',
+        description: 'Manually triggers an integration to send a test payload. Useful for verifying connectivity after a config change or after the integration has been failing. Admin-only because triggering an external POST is a write-side action.',
+        inputSchema,
+        handler: async (input, ctx) => {
+            if (!isIntegrationsAdmin(ctx)) {
+                return deniedEnvelope('Only admins can manually trigger integrations.');
+            }
+            let doc = null;
+            try {
+                doc = (await deps.payload.findByID({
+                    collection: deps.collectionSlug,
+                    id: input.integrationId,
+                }));
+            }
+            catch {
+                doc = null;
+            }
+            if (!doc)
+                return { error: `No integration instance with id "${input.integrationId}".` };
+            if (doc['enabled'] !== true) {
+                return {
+                    error: `Integration "${String(doc['name'])}" is disabled. Enable it in the admin before triggering.`,
+                };
+            }
+            const integrationType = String(doc['integrationType']);
+            await deps.inngest.send({
+                name: 'integration/manual-sync',
+                data: {
+                    integrationId: integrationType,
+                    instanceId: input.integrationId,
+                    triggeredBy: ctx.user?.id ?? null,
+                    reason: input.reason ?? null,
+                },
+            });
+            return {
+                ok: true,
+                triggered: {
+                    instanceId: input.integrationId,
+                    instanceName: String(doc['name']),
+                    type: integrationType,
+                },
+                message: `Triggered manual sync for "${String(doc['name'])}". Check list_integrations or get_integration_status in a few seconds for the result.`,
+            };
+        },
+    };
+}
+//# sourceMappingURL=trigger-sync.js.map

package/dist/tools/trigger-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trigger-sync.js","sourceRoot":"","sources":["../../src/tools/trigger-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAQjE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,CAAC,4DAA4D,CAAC;IACzE,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;CACzE,CAAC,CAAA;AAEF,MAAM,UAAU,qBAAqB,CACnC,IAAqB;IAErB,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,oOAAoO;QACtO,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,cAAc,CAAC,gDAAgD,CAAC,CAAA;YACzE,CAAC;YAED,IAAI,GAAG,GAAmC,IAAI,CAAA;YAC9C,IAAI,CAAC;gBACH,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;oBACjC,UAAU,EAAE,IAAI,CAAC,cAAc;oBAC/B,EAAE,EAAE,KAAK,CAAC,aAAa;iBACxB,CAAC,CAAmC,CAAA;YACvC,CAAC;YAAC,MAAM,CAAC;gBACP,GAAG,GAAG,IAAI,CAAA;YACZ,CAAC;YAED,IAAI,CAAC,GAAG;gBAAE,OAAO,EAAE,KAAK,EAAE,oCAAoC,KAAK,CAAC,aAAa,IAAI,EAAE,CAAA;YACvF,IAAI,GAAG,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO;oBACL,KAAK,EAAE,gBAAgB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,0DAA0D;iBACrG,CAAA;YACH,CAAC;YAED,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAA;YAEtD,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;gBACtB,IAAI,EAAE,yBAAyB;gBAC/B,IAAI,EAAE;oBACJ,aAAa,EAAE,eAAe;oBAC9B,UAAU,EAAE,KAAK,CAAC,aAAa;oBAC/B,WAAW,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,IAAI;oBACjC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;iBAC7B;aACF,CAAC,CAAA;YAEF,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,SAAS,EAAE;oBACT,UAAU,EAAE,KAAK,CAAC,aAAa;oBAC/B,YAAY,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBACjC,IAAI,EAAE,eAAe;iBACtB;gBACD,OAAO,EAAE,8BAA8B,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,uFAAuF;aAClJ,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,116 @@
+import type { Field } from 'payload';
+import type { Inngest, InngestFunction } from 'inngest';
+import type { McpToolDefinition } from '@forumone/throughline-plugin-contract';
+export type IntegrationCategory = 'crm' | 'marketing' | 'analytics' | 'webhook' | 'storage' | 'messaging' | 'other';
+export type IntegrationSyncStatus = 'success' | 'partial' | 'failed' | 'never-run';
+export interface IntegrationConfigValidation {
+    ok: boolean;
+    reason?: string;
+}
+export interface IntegrationHealth {
+    ok: boolean;
+    details?: string;
+}
+/**
+ * The contract every integration module satisfies. Integrations are
+ * registered with the plugin and instantiated per-row via the Integrations
+ * collection. The contract is intentionally small: every future integration
+ * (Salesforce, Mailchimp, etc.) follows the same shape, so the productivity
+ * compounding is in keeping it stable.
+ *
+ * Integrations are events-in, events-out: they subscribe to system events
+ * (e.g. `content/page.published`) via Inngest functions returned by
+ * {@link Integration.createFunctions} and emit their own results events as
+ * needed. They never call other integrations directly.
+ */
+export interface Integration<Config = Record<string, unknown>> {
+    /** Unique slug. Used as the `integrationType` value in the collection. */
+    id: string;
+    /** Display name shown in the admin and `list_integration_types`. */
+    name: string;
+    /** One-line description for the admin and the listing tool. */
+    description: string;
+    /** Category for organizational grouping. */
+    category: IntegrationCategory;
+    /**
+     * Payload field definitions shown in the admin under each instance's
+     * `config` group. Integration authors keep this small and obvious — Claude
+     * cannot edit these (admin-only access) so unhelpful labels become support
+     * tickets, not chatbot mistakes.
+     */
+    configFields: Field[];
+    /**
+     * Validates a config object against this integration's requirements. Run
+     * by the collection's beforeChange hook so the Payload UI surfaces errors
+     * inline rather than failing at sync time.
+     */
+    validateConfig: (config: Config) => Promise<IntegrationConfigValidation>;
+    /** Which system events this integration subscribes to. Documentation only. */
+    subscribes: Array<{
+        event: string;
+        purpose: string;
+    }>;
+    /**
+     * Factory for the Inngest functions this integration contributes. Called
+     * during plugin init; the returned functions are exposed via the registry
+     * so the client app's Inngest endpoint can serve them. See
+     * `docs/integrations-wiring.md`.
+     */
+    createFunctions: (ctx: IntegrationContext) => InngestFunction.Any[];
+    /**
+     * Optional MCP tools the integration adds to the integrations server. Most
+     * integrations need only the five built-in tools; this is for cases where
+     * the integration needs its own purpose-built tool (e.g. Salesforce's
+     * "preview field mapping").
+     */
+    mcpTools?: (ctx: IntegrationContext) => McpToolDefinition[];
+    /**
+     * Health check. Called by the `test_integration` MCP tool. Returns
+     * `{ ok: true }` for healthy or `{ ok: false, details }` for problems.
+     */
+    healthcheck?: (config: Config) => Promise<IntegrationHealth>;
+}
+/**
+ * Runtime context passed to integrations during initialization. Provides
+ * the framework's facilities (Inngest, audit) without coupling the
+ * integration to internal implementation details.
+ */
+export interface IntegrationContext {
+    inngest: Inngest;
+    integrationsCollectionSlug: string;
+    /** Loads all enabled instances of an integration by id. */
+    loadInstances: <Config = Record<string, unknown>>(integrationId: string) => Promise<Array<IntegrationInstanceLoaded<Config>>>;
+    /** Updates an instance's lastSyncAt / lastSyncStatus / lastError. */
+    updateStatus: (instanceId: string, status: IntegrationSyncStatus, error?: string) => Promise<void>;
+    /** Writes an audit event. Thin wrapper over core's audit writer. */
+    recordAudit: (event: IntegrationAuditEvent) => Promise<void>;
+}
+export interface IntegrationInstanceLoaded<Config = Record<string, unknown>> {
+    id: string;
+    name: string;
+    config: Config;
+}
+export interface IntegrationAuditEvent {
+    /** The integration's id (e.g. 'webhook'). Used as the audit `integrationId`. */
+    integrationId: string;
+    /** The instance's display name. Surfaces in audit summaries. */
+    instanceName: string;
+    action: 'integration.synced' | 'integration.failed';
+    summary: string;
+    errorMessage?: string;
+}
+/**
+ * The shape of a single Integrations-collection row, as returned by Payload.
+ * Used by tests and by the helpers that read instances back out.
+ */
+export interface IntegrationInstance {
+    id: string;
+    name: string;
+    integrationType: string;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    lastSyncAt?: string;
+    lastSyncStatus?: IntegrationSyncStatus;
+    lastError?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,10 +1,66 @@
 {
   "name": "@forumone/throughline-integrations",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @forumone/throughline-integrations",
+  "version": "0.2.1",
+  "description": "Plugin architecture for connecting Throughline-powered Payload sites to external systems. Ships the Integration contract, registry, collection, MCP tools, and a generic outbound-webhook integration as the first concrete example.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "throughline",
+    "payload",
+    "mcp",
+    "integrations",
+    "webhook"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forumone/throughline.git",
+    "directory": "packages/integrations"
+  },
+  "homepage": "https://github.com/forumone/throughline/tree/main/packages/integrations#readme",
+  "bugs": {
+    "url": "https://github.com/forumone/throughline/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "inngest": "^4.0.0",
+    "payload": "^3.0.0"
+  },
+  "dependencies": {
+    "zod": "^3.23.0",
+    "@forumone/throughline-core": "0.2.1",
+    "@forumone/throughline-plugin-contract": "0.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "eslint": "^9.15.0",
+    "inngest": "^4.2.0",
+    "payload": "^3.83.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "@forumone/throughline-eslint-config": "0.0.0",
+    "@forumone/throughline-tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b -w",
+    "clean": "rm -rf dist .turbo *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}