@vornrun/connector-sdk 0.6.0-beta.1 → 0.6.0-beta.3

package/dist/{chunk-VBE6WCLN.js → chunk-457KOZUU.js}

@@ -541,6 +541,7 @@ function pollToolName(triggerType) {
   return `poll_${triggerType}`;
 }
 var MANIFEST_TOOL = "vorn_connector_manifest";
+var PREFLIGHT_TOOL = "vorn_connector_preflight";
 function connectionSetup(connector, triggerType) {
   const trigger = connector.triggers.find((entry) => entry.type === triggerType);
   if (!trigger) {
@@ -654,6 +655,33 @@ function createConnectorServer(connector, options = {}) {
     },
     () => json(connectorManifest(connector))
   );
+  if (connector.preflight) {
+    const preflight = connector.preflight.bind(connector);
+    server.registerTool(
+      PREFLIGHT_TOOL,
+      {
+        description: `Check whether ${connector.name} can run right now`,
+        inputSchema: {},
+        // Declared rather than left open like the manifest's: this shape is
+        // fixed, so a caller can validate against it. Still loose, because a
+        // connector adding a field of its own should not fail the call.
+        outputSchema: z.looseObject({
+          ok: z.boolean().describe("Whether the connector could run right now"),
+          message: z.string().optional().describe("What to do about it, when it could not")
+        })
+      },
+      async () => {
+        try {
+          return json({ ...await preflight() });
+        } catch (error) {
+          return json({
+            ok: false,
+            message: error instanceof Error ? error.message : String(error)
+          });
+        }
+      }
+    );
+  }
   for (const trigger of connector.triggers) {
     server.registerTool(
       pollToolName(trigger.type),
@@ -737,6 +765,7 @@ export {
   resolveConfig,
   pollToolName,
   MANIFEST_TOOL,
+  PREFLIGHT_TOOL,
   connectionSetup,
   connectorManifest,
   createConnectorServer,

package/dist/cli.js

@@ -7,7 +7,7 @@ import {
   resolveConfig,
   runPoll,
   serveConnector
-} from "./chunk-VBE6WCLN.js";
+} from "./chunk-457KOZUU.js";
 
 // src/cli.ts
 import { pathToFileURL } from "url";

package/dist/index.d.ts

@@ -218,6 +218,16 @@ interface ConnectorIcon {
     /** SVG path `d` data, drawn with `fill="currentColor"` so it inherits color. */
     paths: string[];
 }
+/**
+ * What a connector reports about its own readiness.
+ *
+ * `message` is shown to the user verbatim, so it should say what to do rather
+ * than what went wrong — "run `gh auth login`" beats "not authenticated".
+ */
+interface PreflightResult {
+    ok: boolean;
+    message?: string;
+}
 interface ConnectorDefinition {
     /** Stable connector id, e.g. `azure-devops`. */
     id: string;
@@ -228,6 +238,26 @@ interface ConnectorDefinition {
     config?: ConnectorConfigField[];
     triggers?: TriggerDefinition[];
     actions?: ActionDefinition[];
+    /**
+     * Whether this connector could work right now, asked before anyone waits on
+     * a poll.
+     *
+     * A connector whose credentials come from config fields does not need this:
+     * a missing field is already a visible, nameable error. One that borrows an
+     * external tool's login — `gh auth login`, `az login` — has no field to be
+     * missing, so without this the first sign that the tool is absent or signed
+     * out is a poll failing some minutes after the connection was saved.
+     *
+     * Answer `ok: false` with a message saying what to do about it. Throwing is
+     * equivalent — the server catches it and reports the same shape with the
+     * error's message — so there is one result for a caller to read and no
+     * behaviour riding on which you choose. Prefer returning when the state is
+     * one you recognise, because then you get to write the sentence.
+     *
+     * Absent means there is nothing to check, which is not the same answer as a
+     * check that passed.
+     */
+    preflight?(): Promise<PreflightResult> | PreflightResult;
 }
 /** A validated definition. Every accessor below is guaranteed non-null. */
 interface Connector extends ConnectorDefinition {
@@ -351,6 +381,12 @@ declare function runAction(connector: Connector, actionType: string, args: Recor
 declare function pollToolName(triggerType: string): string;
 /** Tool that reports the connector's manifest and setup hints. */
 declare const MANIFEST_TOOL = "vorn_connector_manifest";
+/**
+ * Tool that reports whether the connector can run right now. Present only when
+ * the connector declares a `preflight`, so its absence means "nothing to
+ * check" rather than "check passed".
+ */
+declare const PREFLIGHT_TOOL = "vorn_connector_preflight";
 interface ConnectionSetup {
     connectorId: string;
     triggerType: string;
@@ -455,4 +491,4 @@ interface ConnectorHarness {
  */
 declare function createConnectorHarness(connector: Connector, harnessOptions?: HarnessOptions): ConnectorHarness;
 
-export { type ActionContext, type ActionDefinition, type ActionInputField, type CheckFinding, type CheckOptions, type ConnectionSetup, type Connector, type ConnectorConfig, type ConnectorConfigField, type ConnectorDefinition, type ConnectorHarness, type ConnectorIcon, type ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, type DedupeStrategy, type DefaultWorkflow, type FetchContext, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, type NormalizedItem, type PollContext, type PollOutcome, type PollPage, type RunActionOptions, type RunPollOptions, type StatusSuggestion, type TriggerDefinition, checkConnector, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, formatFindings, normalizeItem, normalizeItems, pollToolName, pollWithDedupe, resolveConfig, runAction, runPoll, serveConnector };
+export { type ActionContext, type ActionDefinition, type ActionInputField, type CheckFinding, type CheckOptions, type ConnectionSetup, type Connector, type ConnectorConfig, type ConnectorConfigField, type ConnectorDefinition, type ConnectorHarness, type ConnectorIcon, type ConnectorItem, type ConnectorManifest, type ConnectorServerOptions, type DedupeStrategy, type DefaultWorkflow, type FetchContext, type HarnessOptions, MANIFEST_TOOL, MAX_POLL_PAGES, type NormalizedItem, PREFLIGHT_TOOL, type PollContext, type PollOutcome, type PollPage, type PreflightResult, type RunActionOptions, type RunPollOptions, type StatusSuggestion, type TriggerDefinition, checkConnector, connectionSetup, connectorManifest, createConnectorHarness, createConnectorServer, defineConnector, drainPoll, envNameFor, formatFindings, normalizeItem, normalizeItems, pollToolName, pollWithDedupe, resolveConfig, runAction, runPoll, serveConnector };

package/dist/index.js

@@ -1,6 +1,7 @@
 import {
   MANIFEST_TOOL,
   MAX_POLL_PAGES,
+  PREFLIGHT_TOOL,
   checkConnector,
   connectionSetup,
   connectorManifest,
@@ -17,7 +18,7 @@ import {
   runAction,
   runPoll,
   serveConnector
-} from "./chunk-VBE6WCLN.js";
+} from "./chunk-457KOZUU.js";
 
 // src/harness.ts
 function createConnectorHarness(connector, harnessOptions = {}) {
@@ -52,6 +53,7 @@ function createConnectorHarness(connector, harnessOptions = {}) {
 export {
   MANIFEST_TOOL,
   MAX_POLL_PAGES,
+  PREFLIGHT_TOOL,
   checkConnector,
   connectionSetup,
   connectorManifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vornrun/connector-sdk",
-  "version": "0.6.0-beta.1",
+  "version": "0.6.0-beta.3",
   "description": "Build and share Vorn pull connectors as ordinary npm packages",
   "type": "module",
   "license": "MIT",