@jskit-ai/connectors-catalog 0.2.3 → 0.2.5

package/patterns/paddle-catalogue/PATTERN.md

@@ -38,6 +38,12 @@ the ordinary runtime for each request, preserving authorization and the
 connection's configured sandbox/live environment. The sandbox setting used for
 local schema validation sends no request and does not override runtime routing.
 
+Each collaborator the composition receives (the connection `runtime`) is a
+required parameter typed in a JSDoc `@param` and called directly, without a
+`typeof` probe, a "requires x" guard or a no-op default. A server feature that
+uses it follows
+[typed features](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/site/guide/framework/typed-features.md).
+
 ## Product decisions
 
 For assistant use, authorize the complete cloned request with
@@ -58,12 +64,15 @@ termination can prevent the returned report from being saved, so an application
 needing crash recovery must record each completed step durably. This small
 recipe does not promise crash recovery, rollback or exactly-once execution.
 
+Do not probe a collaborator, default one to `null`, `{}` or a no-op, fill a slot
+with a setter after construction, or keep a module-level registry.
+
 ## Variation points
 
-CLI users can call this same JavaScript recipe with their own runtime. Vibe64
+CLI users can call this same JavaScript recipe with their own runtime. An editor
 configures the project; it does not execute catalogue writes on configuration
 save. Laravel applications implement this composition with their own framework
-and Paddle client, without importing JavaScript or depending on Vibe64.
+and Paddle client, without importing JavaScript or depending on an editor.
 
 ## Example files
 

package/patterns/paddle-catalogue/example/create-products.js

@@ -1,7 +1,10 @@
 import { paddleProvider } from "@jskit-ai/connectors-catalog/server/paddle";
 
-// Application-owned composition: pass an application-mode connection runtime.
-// An assistant host must approve the complete batch before calling this recipe.
+/**
+ * Application-owned composition: pass an application-mode connection runtime.
+ * An assistant host must approve the complete batch before calling this recipe.
+ * @param {{ runtime: import("@jskit-ai/connectors-core/server/types").ConnectorsCore, context: object, integrationId: string, items: object[], signal?: AbortSignal }} request
+ */
 async function createProductsWithPrices({ runtime, context, integrationId, items, signal }) {
   if (!Array.isArray(items) || !items.length || items.length > 100) {
     throw new TypeError("Supply between 1 and 100 products with prices.");

package/patterns/public-image/PATTERN.md

@@ -29,12 +29,18 @@ existing access policy applies before exposing its configured resources.
 
 ## Invariants
 
-- CLI and Vibe64 edit the same reference-only `integrations.json`.
+- The CLI and a hosted editor edit the same reference-only `integrations.json`.
 - Only a `pk_` key enters an image URL; a private key fails validation.
 - URL creation is local and does not establish a verified account connection.
 - Browser load/error events report delivery. A monogram is not proof of a brand logo.
 - Domain restrictions concern the app that loads the image, including previews
   and custom domains. The editor VM may have a different origin.
+- Each collaborator the composition receives (`resolveReference`) is a required
+  parameter typed in a JSDoc `@param` and called directly, without a `typeof`
+  probe, a "requires x" guard or a no-op default. It is typed with
+  `ResolveReference` from `@jskit-ai/connectors-core/server/types`. A server
+  feature that uses it follows
+  [typed features](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/site/guide/framework/typed-features.md).
 
 ## Framework APIs
 
@@ -82,3 +88,6 @@ These checks need neither live credentials nor generated sample applications.
 Do not call server `connectApiKey` to manufacture a Connected receipt for this
 image flow. Do not send a secret key, an environment dump or a caller-selected
 service origin to the browser. Do not treat key naming as provider quota isolation.
+
+Do not probe a collaborator, default one to `null`, `{}` or a no-op, fill a slot
+with a setter after construction, or keep a module-level registry.

package/patterns/public-image/example/logo-url.js

@@ -2,7 +2,10 @@ import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/
 import { logoDevDefinition } from "@jskit-ai/connectors-catalog/shared";
 import { createLogoDevImageUrl } from "@jskit-ai/connectors-catalog/client/logo-dev";
 
-// The application authorizes access before passing its configuration and resolver.
+/**
+ * The application authorizes access before passing its configuration and resolver.
+ * @param {{ configurationText: string, integrationId: string, resolveReference: import("@jskit-ai/connectors-core/server/types").ResolveReference, image: object }} request
+ */
 async function logoUrlFromConfiguration({ configurationText, integrationId, resolveReference, image }) {
   const configuration = parseIntegrationConfiguration(configurationText, { providers: [logoDevDefinition], allowUnknownProviders: true });
   const integration = configuration.integrations[integrationId];

package/patterns/redshift-queries/PATTERN.md

@@ -24,7 +24,7 @@ SQL can modify data; read-only behavior requires appropriate database grants.
 
 ## Product decisions
 
-Select serverless or provisioned in the same JSON edited by Vibe64. Serverless
+Select serverless or provisioned in the same JSON the editor edits. Serverless
 requires a workgroup name; provisioned requires a cluster identifier and may use
 an explicit database user. Both require a database and region. Store AWS secrets
 outside the file. Temporary credentials additionally need `sessionTokenRef` and

package/patterns/source-scanning/PATTERN.md

@@ -18,7 +18,7 @@ The example wires that library to application-owned authority and snapshot looku
 ## Do not use when
 
 This is not an HTTP application-data connector, user login, a managed gateway,
-or an implementation of Vibe64's coding agents. It does not generate an app.
+or an implementation of a hosted editor's coding agents. It does not generate an app.
 Auth0 and native Windows execution are not implemented in the current runner.
 
 ## Product decisions
@@ -39,7 +39,15 @@ and whether a blocking verdict prevents a later operation.
 - Missing/invalid reports, cancellation and failed scans never become clean scans.
 - Provider credentials are isolated from coding-agent sessions and credentials.
 - The host supplies its own authorized provider credentials; editor edition does
-  not select a shared Vibe64 provider account.
+  not select a shared hosted provider account.
+- Each collaborator the composition receives (`authorize`, `resolveReference`
+  and `resolveScanTarget`) is a required parameter typed in a JSDoc `@param` and
+  called directly, without a `typeof` probe, a "requires x" guard or a no-op
+  default. `authorize` and `resolveReference` are typed with `ConnectorAuthorize`
+  and `ResolveReference` from `@jskit-ai/connectors-core/server/types`, and
+  `resolveScanTarget` with `WizScanTargetResolver` from
+  `@jskit-ai/connectors-catalog/server/types`. A server feature that uses it follows
+  [typed features](https://github.com/mobily-enterprises/jskit-ai/blob/main/packages/agent-docs/site/guide/framework/typed-features.md).
 
 ## Framework APIs
 
@@ -81,3 +89,6 @@ and findings require separately authorised provider acceptance.
 Do not infer workspace grants from a shared slot, return raw provider stderr,
 replay scans automatically, pass arbitrary CLI flags, use a mutable working tree
 as if it were a fixed revision, or substitute a generic API reader for source scans.
+
+Do not probe a collaborator, default one to `null`, `{}` or a no-op, fill a slot
+with a setter after construction, or keep a module-level registry.

package/patterns/source-scanning/example/source-scanner.js

@@ -3,6 +3,15 @@ import { parseIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/
 import { wizDefinition } from "@jskit-ai/connectors-catalog/shared";
 import { createWizScanner } from "@jskit-ai/connectors-catalog/server/wiz";
 
+/**
+ * @param {object} dependencies
+ * @param {string} [dependencies.configFile]
+ * @param {string} dependencies.installedWizCliPath
+ * @param {import("@jskit-ai/connectors-core/server/types").ConnectorAuthorize} dependencies.authorize The application's access policy.
+ * @param {import("@jskit-ai/connectors-core/server/types").ResolveReference} dependencies.resolveReference
+ * @param {import("@jskit-ai/connectors-catalog/server/types").WizScanTargetResolver} dependencies.resolveScanTarget
+ * @param {Record<string, string>} [dependencies.environment]
+ */
 export async function projectSourceScanner({ configFile = "integrations.json", installedWizCliPath,
   authorize, resolveReference, resolveScanTarget, environment }) {
   const configuration = parseIntegrationConfiguration(await readFile(configFile, "utf8"), {

package/src/server/ai.js

@@ -2,9 +2,17 @@ import { ConnectorError, createEnvironmentReferenceResolver } from "@jskit-ai/co
 import { validateIntegrationConfiguration } from "@jskit-ai/connectors-core/shared/configuration";
 import { aiCatalogue, aiDefinition, getAiModel } from "../shared/ai.js";
 
-// A server-only credential boundary. The consuming application's SDK owns all
-// inference, transport, streaming, tool execution and error/fallback policy.
-function createAiConnectionResolver({ configuration, authorize, resolveReference = createEnvironmentReferenceResolver() }) {
+/**
+ * A server-only credential boundary. The consuming application's SDK owns all
+ * inference, transport, streaming, tool execution and error/fallback policy.
+ * @param {object} options
+ * @param {Record<string, any>} options.configuration The integration configuration.
+ * @param {import("@jskit-ai/connectors-core/server/types").ConnectorAuthorize} options.authorize
+ * @param {import("@jskit-ai/connectors-core/server/types").ResolveReference} [options.resolveReference]
+ *   Reads `env:NAME` references from the environment unless the application resolves its own.
+ */
+function createAiConnectionResolver({ configuration, authorize, resolveReference = createEnvironmentReferenceResolver(process.env) }) {
+  // readable-check: allow method-probe - input validation: the application passes its access policy
   if (typeof authorize !== "function") throw new TypeError("AI connections require application authorization.");
   const config = validateIntegrationConfiguration(configuration, { providers: [aiDefinition], allowUnknownProviders: true });
 
@@ -37,9 +45,15 @@ function createAiConnectionResolver({ configuration, authorize, resolveReference
     }
     // Never expose this result through a browser API or include it in logs.
     // Missing baseURL means use the named provider SDK's own default endpoint.
-    return Object.freeze({ providerId: provider.id, model: model.id, sdkPackage: model.sdkPackage,
+    return Object.freeze({
+      providerId: provider.id,
+      model: model.id,
+      sdkPackage: model.sdkPackage,
       modelLimits: Object.freeze({ ...model.limit }),
-      ...(provider.baseURL ? { baseURL: provider.baseURL } : {}), apiKey, access: model.access });
+      ...(provider.baseURL ? { baseURL: provider.baseURL } : {}),
+      apiKey,
+      access: model.access
+    });
   }
   return Object.freeze({ resolve });
 }

package/src/server/apify.js

@@ -1,4 +1,4 @@
-import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { ConnectorError, providerStatusError } from "@jskit-ai/connectors-core/server";
 import { apifyDefinition } from "../shared/tokens.js";
 import { jsonOperation, validatedOperation } from "./jsonOperation.js";
 
@@ -13,7 +13,7 @@ const apifyProvider = Object.freeze({
     const response = await fetchImpl(url, { ...options, credentials: "omit", redirect: "error" });
     if (!response.ok) {
       await response.body?.cancel();
-      throw Object.assign(new Error("Apify storage request failed."), { status: response.status });
+      throw providerStatusError(response.status);
     }
     const reader = response.body?.getReader();
     const chunks = [];

package/src/server/asana.js

@@ -1,6 +1,7 @@
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { asanaDefinition } from "../shared/tokens.js";
 import { jsonOperation, validatedOperation } from "./jsonOperation.js";
+import { hasDataList } from "./connectorValues.js";
 
 const gid = { type: "string", minLength: 1, maxLength: 100, pattern: "^[0-9]+$" };
 const requiredGid = { ...gid, required: true };
@@ -17,7 +18,6 @@ const project = { ...common, archived: { type: "boolean" }, owner: { ...gid, nul
 const taskFields = "gid,name,notes,completed,assignee.gid,assignee.name,due_on,start_on,projects.gid,parent.gid";
 const projectFields = "gid,name,notes,archived,owner.gid,privacy_setting,due_on,start_on,workspace.gid";
 const record = result => typeof result?.data?.gid === "string";
-const list = result => Array.isArray(result?.data);
 function read(endpoint, input = {}, fields) {
   const url = new URL(`https://app.asana.com/api/1.0/${endpoint}`);
   for (const [key, value] of Object.entries(input)) url.searchParams.set(key, String(value));
@@ -40,21 +40,21 @@ const asanaProvider = Object.freeze({
   apiKey: { headers: (key) => ({ Authorization: `Bearer ${key}` }) },
   checkOperation: "workspaces.list",
   operations: {
-    "workspaces.list": jsonOperation("https://app.asana.com/api/1.0/workspaces", page, list),
+    "workspaces.list": jsonOperation("https://app.asana.com/api/1.0/workspaces", page, hasDataList),
     "projects.list": validatedOperation({ workspace: requiredGid, ...page, archived: { type: "boolean" } },
-      input => read("projects", input, projectFields), list),
+      input => read("projects", input, projectFields), hasDataList),
     "projects.get": validatedOperation({ gid: requiredGid }, ({ gid }) => read(`projects/${gid}`, {}, projectFields), record),
     "projects.create": write("POST", "projects", { ...project, name: { ...common.name, required: true },
       workspace: requiredGid, privacy_setting: { ...project.privacy_setting, required: true } }, projectFields),
     "projects.update": write("PUT", "projects", project, projectFields),
     "tasks.list": validatedOperation({ project: requiredGid, ...page, completed_since: { type: "string", maxLength: 100 } },
-      ({ project, ...input }) => read(`projects/${project}/tasks`, input, taskFields), list),
+      ({ project, ...input }) => read(`projects/${project}/tasks`, input, taskFields), hasDataList),
     "tasks.get": validatedOperation({ gid: requiredGid }, ({ gid }) => read(`tasks/${gid}`, {}, taskFields), record),
     "tasks.create": write("POST", "tasks", { ...task, name: { ...common.name, required: true }, workspace: requiredGid,
       projects: { type: "array", items: gid, validator: values => values.length <= 100 || "Choose at most 100 projects." } }, taskFields),
     "tasks.update": write("PUT", "tasks", task, taskFields),
-    "users.list": validatedOperation({ workspace: requiredGid, ...page }, ({ workspace, ...input }) => read(`workspaces/${workspace}/users`, input), list),
-    "teams.list": validatedOperation({ workspace: requiredGid, ...page }, ({ workspace, ...input }) => read(`workspaces/${workspace}/teams`, input), list),
+    "users.list": validatedOperation({ workspace: requiredGid, ...page }, ({ workspace, ...input }) => read(`workspaces/${workspace}/users`, input), hasDataList),
+    "teams.list": validatedOperation({ workspace: requiredGid, ...page }, ({ workspace, ...input }) => read(`workspaces/${workspace}/teams`, input), hasDataList),
     "projectMembers.add": validatedOperation({ project: requiredGid, member: requiredGid,
       access_level: { type: "string", required: true, enum: ["admin", "editor", "commenter"] } },
       ({ project, member, access_level }) => ({ method: "POST", url: "https://app.asana.com/api/1.0/memberships",

package/src/server/ashby.js

@@ -1,10 +1,11 @@
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { ashbyDefinition } from "../shared/tokens.js";
 import { jsonOperation } from "./jsonOperation.js";
+import { UUID_SOURCE } from "../shared/uuid.js";
 
 const text = { type: "string", minLength: 1, maxLength: 256 };
 const uuid = { type: "string", required: true,
-  pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" };
+  pattern: `^${UUID_SOURCE}$` };
 const page = { limit: { type: "integer", min: 1, max: 100, defaultTo: 25 },
   cursor: { type: "string", minLength: 1, maxLength: 8192 }, syncToken: { type: "string", minLength: 1, maxLength: 8192 } };
 const candidate = { name: text, email: { ...text, pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" }, phoneNumber: text };

package/src/server/attention.js

@@ -2,6 +2,8 @@ import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { createSchema } from "json-rest-schema";
 import { attentionDefinition } from "../shared/tokens.js";
 import { jsonOperation, validatedOperation, withQuery } from "./jsonOperation.js";
+import { hasDataList } from "./connectorValues.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const text = { type: "string", minLength: 1, maxLength: 2000 };
 const id = { type: "string", minLength: 1, maxLength: 100, pattern: "^[A-Za-z0-9_-]+$" };
@@ -10,9 +12,8 @@ const ids = { type: "array", items: id, validator: value => value.length <= 100
 const bool = { type: "boolean" };
 const page = { page: { type: "integer", min: 1, defaultTo: 1 }, size: { type: "integer", min: 1, max: 200, defaultTo: 50 } };
 const dateTime = { ...text, validator: value => /^\d{4}-\d{2}-\d{2}T/.test(value) && Number.isFinite(Date.parse(value)) || "Use an ISO timestamp." };
-const list = result => Array.isArray(result?.data);
-const record = result => result?.data !== null && typeof result?.data === "object" && !Array.isArray(result.data) && typeof (result.data.uuid ?? result.data.id) === "string";
-const conversation = result => result?.type === "conversations" && typeof result.id === "string" && result.attributes !== null && typeof result.attributes === "object" && !Array.isArray(result.attributes);
+const record = result => isRecord(result?.data) && typeof (result.data.uuid ?? result.data.id) === "string";
+const conversation = result => result?.type === "conversations" && typeof result.id === "string" && isRecord(result.attributes);
 function operation(method, endpoint, fields, validateResult, prepare = value => value) {
   return validatedOperation(fields, values => {
     const { id: resource, ...body } = prepare(values);
@@ -49,19 +50,19 @@ const attentionProvider = Object.freeze({
     "analysis.ask": operation("POST", "ask_attention/v2", { conversations_ids: { ...ids, required: true },
       deal_id: { type: "string", required: true, maxLength: 100 }, prompt: { ...text, required: true, maxLength: 20000 }
     }, result => Array.isArray(result) && result.every(item => typeof item?.output === "string" && typeof item.error === "string" && typeof item.conversation_id === "string")),
-    "scorecards.list": operation("GET", "scorecards", page, list),
+    "scorecards.list": operation("GET", "scorecards", page, hasDataList),
     "scorecards.get": operation("GET", "scorecards/{id}", { id: requiredId }, record),
-    "scorecardItems.list": operation("GET", "scorecards/{id}/items", { id: requiredId, ...page }, list),
+    "scorecardItems.list": operation("GET", "scorecards/{id}/items", { id: requiredId, ...page }, hasDataList),
     "scorecards.summary": operation("POST", "scorecards/summary", { fromDateTime: { ...dateTime, required: true }, toDateTime: { ...dateTime, required: true },
       scorecardUUID: requiredId, scorecardsItemsUUIDs: { ...ids, required: true }, teamUUIDs: { ...ids, required: true }, userUUIDs: { ...ids, required: true }
-    }, list, value => { if (Date.parse(value.fromDateTime) >= Date.parse(value.toDateTime)) throw new ConnectorError("connector_input_invalid", "End time must follow start time.", { statusCode: 422, messageCode: "connectors.attention.endTimeMustFollowStart" }); return value; }),
+    }, hasDataList, value => { if (Date.parse(value.fromDateTime) >= Date.parse(value.toDateTime)) throw new ConnectorError("connector_input_invalid", "End time must follow start time.", { statusCode: 422, messageCode: "connectors.attention.endTimeMustFollowStart" }); return value; }),
     "scorecardResults.create": operation("POST", "createScorecardResult", { scorecard_uuid: requiredId, conversation_uuid: requiredId,
       summary: { ...text, required: true, maxLength: 20000 }, items: { type: "array", required: true,
         items: { type: "object", schema: createSchema({ scorecard_item_uuid: requiredId, numeric_result: { type: "integer" }, description: { ...text, required: true } }) },
         validator: value => value.length > 0 && value.length <= 100 || "Supply 1–100 scoring items." }
     }, result => result?.success === true),
-    "users.list": operation("GET", "organizations/users", { teamUUID: id }, list),
-    "roles.list": operation("GET", "organizations/roles", {}, list),
+    "users.list": operation("GET", "organizations/users", { teamUUID: id }, hasDataList),
+    "roles.list": operation("GET", "organizations/roles", {}, hasDataList),
     "users.create": operation("POST", "organizations/users", { email: { ...text, required: true, pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" },
       first_name: { ...text, required: true }, last_name: { ...text, required: true }, roleUUID: requiredId,
       seat_type: { type: "string", required: true, enum: ["listener", "recording"] },
@@ -71,8 +72,8 @@ const attentionProvider = Object.freeze({
       roleUUID: id, seat_type: { type: "string", enum: ["listener", "recording"] }, teamUUIDsToRemove: ids,
       teamsToAdd: { type: "array", items: team, validator: value => value.length <= 100 || "Use at most 100 teams." }
     }, record),
-    "users.delete": operation("DELETE", "organizations/users/{id}", { id: requiredId }, result => result === null || result !== null && typeof result === "object" && !Array.isArray(result) && Object.keys(result).length === 0),
-    "teams.list": operation("GET", "organizations/teams", {}, list),
+    "users.delete": operation("DELETE", "organizations/users/{id}", { id: requiredId }, result => result === null || isRecord(result) && Object.keys(result).length === 0),
+    "teams.list": operation("GET", "organizations/teams", {}, hasDataList),
     "teams.create": operation("POST", "organizations/teams", { name: { ...text, required: true }, parentTeamUUID: id }, record),
     "teams.update": operation("PATCH", "organizations/teams/{id}", { id: requiredId, name: text, parentTeamUUID: id }, record),
     "conversations.list": jsonOperation("https://api.attention.tech/v2/conversations/list", {
@@ -82,7 +83,7 @@ const attentionProvider = Object.freeze({
       "filter[hide_internal]": { type: "boolean" },
       detailedTranscript: { type: "boolean", defaultTo: false }
     }, (result) => Array.isArray(result?.data) && (result.meta === undefined ||
-      result.meta !== null && typeof result.meta === "object" && !Array.isArray(result.meta) &&
+      isRecord(result.meta) &&
       ["totalRecords", "pageCount", "pageNumber", "pageSize"].every((field) => result.meta[field] === undefined ||
         Number.isInteger(result.meta[field]) && result.meta[field] >= 0)))
   }

package/src/server/awsTransport.js

@@ -18,6 +18,12 @@ function awsOperation(service, command, fields, makeInput, validateResult, scope
 }
 
 function awsExchange(service, Client, execute) {
+  /**
+   * Sends one AWS request, signed with the connection's access key bindings.
+   * @param {string} endpoint
+   * @param {object} options
+   * @param {import("@jskit-ai/connectors-core/server/types").ConnectorExchangeTransport} transport
+   */
   return async (endpoint, options, { settings, apiKey, resolveReference, fetchImpl }) => {
     let credentials;
     try {

package/src/server/bigquery.js

@@ -3,6 +3,7 @@ import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { jsonOperation, validatedOperation } from "./jsonOperation.js";
 import { bigqueryDefinition } from "../shared/google.js";
 import { googleRead, googleProvider, pageToken } from "./google.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 const origin = "https://bigquery.googleapis.com";
 const queryScopes = ["https://www.googleapis.com/auth/bigquery", "https://www.googleapis.com/auth/cloud-platform"];
 const resultFields = {
@@ -13,9 +14,9 @@ const resultFields = {
 const resultsSchema = createSchema({ ...resultFields,
   jobId: { type: "string", required: true, minLength: 1, maxLength: 1024, pattern: "^[a-zA-Z0-9_-]+$" }, pageToken: { ...pageToken, noTrim: true }
 });
-const validQueryResult = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value) && !value.error &&
+const validQueryResult = (value) => Boolean(isRecord(value) && !value.error &&
   typeof value.jobComplete === "boolean" && (value.rows === undefined || Array.isArray(value.rows) && value.rows.every((row) =>
-    Array.isArray(row?.f) && row.f.every((cell) => cell && typeof cell === "object" && !Array.isArray(cell) && Object.hasOwn(cell, "v")))) &&
+    Array.isArray(row?.f) && row.f.every((cell) => isRecord(cell) && Object.hasOwn(cell, "v")))) &&
   (value.schema === undefined || Array.isArray(value.schema?.fields)) &&
   (value.pageToken === undefined || typeof value.pageToken === "string") &&
   (value.totalRows === undefined || (typeof value.totalRows === "string" && /^\d+$/.test(value.totalRows))) &&
@@ -41,7 +42,7 @@ const metadataPage = { maxResults: resultFields.maxResults, pageToken: { ...page
 const jobFields = { jobId: resultsSchema.getFieldDefinitions().jobId, location: resultFields.location };
 const validJob = (job) => Boolean(typeof job?.jobReference?.jobId === "string" && job.jobReference.jobId.length > 0 && typeof job.jobReference.projectId === "string" &&
   ["PENDING", "RUNNING", "DONE"].includes(job.status?.state));
-const validPage = (result, field, reference) => Boolean(result && typeof result === "object" && !Array.isArray(result) && !result.error &&
+const validPage = (result, field, reference) => Boolean(isRecord(result) && !result.error &&
   (result[field] === undefined || Array.isArray(result[field]) && result[field].every((item) => typeof item?.[reference]?.projectId === "string")) &&
   (result.nextPageToken === undefined || typeof result.nextPageToken === "string"));
 
@@ -86,7 +87,7 @@ const bigqueryProvider = googleProvider(bigqueryDefinition, origin, "projects.li
   "projects.list": googleRead(["bigquery.readonly", "bigquery", "cloud-platform.read-only", "cloud-platform"], {
     maxResults: { type: "integer", min: 1, max: 50, defaultTo: 50 }, pageToken
   }, (query) => ({ url: `${origin}/bigquery/v2/projects`, query }),
-  (result) => Boolean(result && typeof result === "object" && !Array.isArray(result) && !result.error
+  (result) => Boolean(isRecord(result) && !result.error
     && Number.isInteger(result.totalItems) && result.totalItems >= 0
     && (Array.isArray(result.projects) || (result.totalItems === 0 && result.projects === undefined))))
 });

package/src/server/brevo.js

@@ -2,6 +2,7 @@ import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { createSchema } from "json-rest-schema";
 import { brevoDefinition } from "../shared/tokens.js";
 import { jsonOperation, validatedOperation, withQuery } from "./jsonOperation.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const text = { type: "string", minLength: 1, maxLength: 1000 };
 const email = { ...text, maxLength: 320, pattern: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$" };
@@ -13,7 +14,7 @@ const mailbox = { type: "object", schema: createSchema({ email: { ...email, requ
 const ids = { type: "array", items: { type: "integer", min: 1 }, validator: value => value.length <= 100 || "Use at most 100 list IDs." };
 const emails = { type: "array", items: email, validator: value => value.length > 0 && value.length <= 150 || "Supply 1–150 email addresses." };
 const domain = { type: "string", minLength: 3, maxLength: 253, pattern: "^(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$", required: true };
-const empty = result => result === null || result !== null && typeof result === "object" && !Array.isArray(result) && Object.keys(result).length === 0;
+const empty = result => result === null || isRecord(result) && Object.keys(result).length === 0;
 const record = result => Number.isInteger(result?.id);
 function operation(method, endpoint, fields, validateResult, prepare = value => value) {
   return validatedOperation(fields, values => {

package/src/server/clay.js

@@ -2,6 +2,7 @@ import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { clayDefinition } from "../shared/tokens.js";
 import { jsonOperation } from "./jsonOperation.js";
+import { hasDataList } from "./connectorValues.js";
 
 const endpoint = "https://api.clay.com/public/v0";
 const pageSchema = createSchema({
@@ -57,7 +58,7 @@ const clayProvider = Object.freeze({
         group_by: array(text, 5), order_by: array(object, 3)
       }) },
       cursor: text, limit: { type: "integer", min: 1, max: 100, defaultTo: 50 }
-    }, result => Array.isArray(result?.data), "POST"),
+    }, hasDataList, "POST"),
     "searches.create": jsonOperation(`${endpoint}/search/query-mode`, {
       query: { type: "string", required: true, minLength: 1, maxLength: 16000,
         validator: (value) => value.trim().length > 0 || "Enter a Clay search query." }

package/src/server/clickhouse.js

@@ -1,6 +1,7 @@
 import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
 import { clickhouseDefinition } from "../shared/clickhouse.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const name = { type: "string", required: true, minLength: 1, maxLength: 256,
   validator: (value) => !/[\p{Cc}]/u.test(value) || "Use a name without control characters." };
@@ -31,7 +32,7 @@ function queryOperation(query, fields, validateData, parameters = values => valu
       return Boolean(result && !result.exception && !result.error && Array.isArray(result.meta) &&
         result.meta.every((column) => typeof column?.name === "string" && typeof column.type === "string") &&
         Array.isArray(result.data) && result.data.length <= 100 && Number.isInteger(result.rows) && result.rows === result.data.length &&
-        result.data.every((row) => row && typeof row === "object" && !Array.isArray(row)) && (!validateData || validateData(result.data)));
+        result.data.every(isRecord) && (!validateData || validateData(result.data)));
     }
   };
 }

package/src/server/confidence.js

@@ -10,7 +10,12 @@ const oauth = Object.freeze({ issuer: origin, authorization_endpoint: `${origin}
 
 function provider(definition, path) {
   return Object.freeze({
-    ...definition, oauth, oauthResource: `${origin}/mcp`, apiOrigins: [origin], checkOperation: "tools.list", exchange: exchangeMcp,
+    ...definition,
+    oauth,
+    oauthResource: `${origin}/mcp`,
+    apiOrigins: [origin],
+    checkOperation: "tools.list",
+    exchange: exchangeMcp,
     operations: Object.fromEntries(Object.entries(mcpOperations(() => `${origin}/mcp/${path}`)).map(([name, operation]) => [name, { ...operation, scopes: ["openid"] }]))
   });
 }

package/src/server/connectorValues.js

@@ -0,0 +1,33 @@
+// The value checks several providers share when they validate a provider's response or settings.
+
+/**
+ * A safe integer that is zero or more, such as a count or a version number.
+ * @param {unknown} value
+ */
+const isCount = (value) => Number.isSafeInteger(value) && value >= 0;
+
+/**
+ * A non-empty string.
+ * @param {unknown} value
+ */
+const isText = (value) => typeof value === "string" && value.length > 0;
+
+/**
+ * A response record that carries a string `id`.
+ * @param {any} value
+ */
+const hasStringId = (value) => typeof value?.id === "string";
+
+/**
+ * A response whose `data` is a list.
+ * @param {any} result
+ */
+const hasDataList = (result) => Array.isArray(result?.data);
+
+/**
+ * The origin of the account URL a connection's settings hold.
+ * @param {{ accountUrl: string }} settings
+ */
+const accountOrigin = (settings) => new URL(settings.accountUrl).origin;
+
+export { isCount, isText, hasStringId, hasDataList, accountOrigin };

package/src/server/databricks.js

@@ -1,19 +1,19 @@
-import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { ConnectorError, providerStatusError } from "@jskit-ai/connectors-core/server";
 import { databricksDefinition } from "../shared/databricks.js";
 import { jsonOperation } from "./jsonOperation.js";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
 
 const origin = (settings) => new URL(settings.workspaceUrl).origin;
-const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 const identifier = (value) => Number.isSafeInteger(value) && value > 0;
 const pageToken = { type: "string", minLength: 1, maxLength: 8192 };
 const pagination = (value) => ["next_page_token", "prev_page_token"].every((key) => value[key] === undefined ||
   typeof value[key] === "string" && value[key].length > 0 && value[key].length <= 8192);
-const job = (value) => object(value) && identifier(value.job_id) &&
-  (value.settings === undefined || object(value.settings)) && (value.has_more === undefined || typeof value.has_more === "boolean");
+const job = (value) => isRecord(value) && identifier(value.job_id) &&
+  (value.settings === undefined || isRecord(value.settings)) && (value.has_more === undefined || typeof value.has_more === "boolean");
 const jobsList = jsonOperation((settings) => `${origin(settings)}/api/2.2/jobs/list`, {
   limit: { type: "integer", min: 1, max: 100, defaultTo: 20 },
   expand_tasks: { type: "boolean", defaultTo: false }, name: { type: "string", minLength: 1, maxLength: 4096 }, page_token: pageToken
-}, (value) => object(value) && pagination(value) && (value.jobs === undefined || Array.isArray(value.jobs) && value.jobs.every(job)));
+}, (value) => isRecord(value) && pagination(value) && (value.jobs === undefined || Array.isArray(value.jobs) && value.jobs.every(job)));
 const jobsGet = jsonOperation((settings) => `${origin(settings)}/api/2.2/jobs/get`, {
   job_id: { type: "integer", required: true, min: 1, max: Number.MAX_SAFE_INTEGER },
   include_trigger_state: { type: "boolean", defaultTo: false }, page_token: pageToken
@@ -41,10 +41,10 @@ const databricksProvider = Object.freeze({
     const url = new URL(address);
     // An empty jobs list is {}, but JSON null or an unparseable body is not a verified list.
     const response = await fetchImpl(address, { ...options, credentials: "omit" });
-    if (!response.ok) throw Object.assign(new Error("Databricks request failed."), { status: response.status });
+    if (!response.ok) throw providerStatusError(response.status);
     let result;
     try { result = await response.json(); } catch { /* checked below */ }
-    if (response.status !== 200 || !object(result) || result.error_code || result.error ||
+    if (response.status !== 200 || !isRecord(result) || result.error_code || result.error ||
       (url.pathname.endsWith("/list") && result?.jobs?.length > Number(url.searchParams.get("limit"))) ||
       (url.pathname.endsWith("/get") && result?.job_id !== Number(url.searchParams.get("job_id")))) {
       throw new ConnectorError("connector_response_invalid", "Databricks returned an unexpected job response.", { statusCode: 502, messageCode: "connectors.databricks.returnedUnexpectedJobResponse" });

package/src/server/dbt-semantic-layer.js

@@ -2,10 +2,10 @@ import { createSchema } from "json-rest-schema";
 import { ConnectorError } from "@jskit-ai/connectors-core/server";
 import { dbtSemanticLayerDefinition } from "../shared/dbt-semantic-layer.js";
 import { graphqlOperation } from "./graphqlOperation.js";
+import { isText } from "./connectorValues.js";
 
 const origin = (settings) => `https://${settings.host}`;
 const endpoint = (settings) => `${origin(settings)}/api/graphql`;
-const text = (value) => typeof value === "string" && value.length > 0;
 const description = (value) => value === null || typeof value === "string";
 const paging = {
   pageNum: { type: "integer", min: 1, max: 2_147_483_647, defaultTo: 1 },
@@ -14,7 +14,7 @@ const paging = {
 };
 const pageFields = "pageNum pageSize totalItems totalPages items { name description type }";
 const validPage = (page, typed = true) => Array.isArray(page?.items) && page.items.length <= 100 &&
-  page.items.every((item) => text(item?.name) && description(item.description) && (!typed || text(item.type))) &&
+  page.items.every((item) => isText(item?.name) && description(item.description) && (!typed || isText(item.type))) &&
   Number.isSafeInteger(page.pageNum) && page.pageNum >= 1 && Number.isSafeInteger(page.pageSize) && page.pageSize >= 1 && page.pageSize <= 100 &&
   Number.isSafeInteger(page.totalItems) && page.totalItems >= page.items.length && Number.isSafeInteger(page.totalPages) && page.totalPages >= 0;
 
@@ -43,15 +43,15 @@ const dbtSemanticLayerProvider = Object.freeze({
       where: { type: "array", validator: (value) => value.length <= 20 || "Use at most 20 filters.",
         items: { type: "object", schema: createSchema({ sql: { type: "string", required: true, minLength: 1, maxLength: 4000 } }) } },
       limit: { type: "integer", min: 1, max: 10000, defaultTo: 100 }
-    }, (data) => text(data?.createQuery?.queryId)),
+    }, (data) => isText(data?.createQuery?.queryId)),
     "queries.get": environmentOperation("query ConnectorDbtQueryResult($environmentId: BigInt!, $queryId: String!, $pageNum: Int!) { query(environmentId: $environmentId, queryId: $queryId, pageNum: $pageNum) { status error totalPages jsonResult(orient: TABLE, encoded: false) } }", {
       queryId: { type: "string", required: true, minLength: 1, maxLength: 512 },
       pageNum: { type: "integer", min: 1, max: 2_147_483_647, defaultTo: 1 }
-    }, (data) => text(data?.query?.status) && description(data.query.error) &&
+    }, (data) => isText(data?.query?.status) && description(data.query.error) &&
       (data.query.totalPages === null || (Number.isSafeInteger(data.query.totalPages) && data.query.totalPages >= 0)) &&
       (data.query.jsonResult === null || (typeof data.query.jsonResult === "object" && Array.isArray(data.query.jsonResult?.data) && Array.isArray(data.query.jsonResult?.schema?.fields)))),
     "environment.read": environmentOperation("query ConnectorDbtEnvironment($environmentId: BigInt!) { environmentInfo(environmentId: $environmentId) { dialect } }", {},
-      (data) => text(data?.environmentInfo?.dialect)),
+      (data) => isText(data?.environmentInfo?.dialect)),
     "metrics.list": environmentOperation(`query ConnectorDbtMetrics($environmentId: BigInt!, $pageNum: Int!, $pageSize: Int!, $search: String) { metricsPaginated(environmentId: $environmentId, pageNum: $pageNum, pageSize: $pageSize, search: $search) { ${pageFields} } }`, paging,
       (data) => validPage(data?.metricsPaginated)),
     "dimensions.list": environmentOperation(`query ConnectorDbtDimensions($environmentId: BigInt!, $metrics: [MetricInput!]!, $pageNum: Int!, $pageSize: Int!, $search: String) { dimensionsPaginated(environmentId: $environmentId, metrics: $metrics, pageNum: $pageNum, pageSize: $pageSize, search: $search) { ${pageFields} } }`, {

package/src/server/elevenlabs.js

@@ -1,6 +1,6 @@
 import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
-import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { ConnectorError, providerStatusError } from "@jskit-ai/connectors-core/server";
 import { elevenlabsDefinition } from "../shared/tokens.js";
 import { jsonOperation } from "./jsonOperation.js";
 
@@ -36,7 +36,7 @@ const elevenlabsProvider = Object.freeze({
     if (!new URL(url).pathname.startsWith("/v1/text-to-speech/")) return request(url, options);
     const response = await fetchImpl(url, { ...options, body: JSON.stringify(options.body),
       headers: { ...options.headers, "Content-Type": "application/json", Accept: "audio/*" }, credentials: "omit", redirect: "error" });
-    if (!response.ok) { await response.body?.cancel(); throw Object.assign(new Error("ElevenLabs speech request failed."), { status: response.status }); }
+    if (!response.ok) { await response.body?.cancel(); throw providerStatusError(response.status); }
     const contentType = response.headers.get("content-type")?.split(";")[0] || "application/octet-stream";
     if (!contentType.startsWith("audio/") && contentType !== "application/octet-stream") {
       await response.body?.cancel(); throw new ConnectorError("connector_response_invalid", "ElevenLabs did not return audio.", { statusCode: 502, messageCode: "connectors.elevenlabs.didNotReturnAudio" });

package/src/server/firebase-cloud-messaging.js

@@ -1,7 +1,7 @@
 import { importPKCS8, SignJWT } from "jose";
 import { createSchema } from "json-rest-schema";
 import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
-import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { ConnectorError, providerStatusError } from "@jskit-ai/connectors-core/server";
 import { firebaseCloudMessagingDefinition, firebaseMessagingScope, firebaseProjectId } from "../shared/firebase-cloud-messaging.js";
 import { jsonOperation } from "./jsonOperation.js";
 
@@ -99,7 +99,7 @@ const firebaseCloudMessagingProvider = Object.freeze({
       if (response.status === 400) {
         throw new ConnectorError("connector_message_invalid", "Firebase rejected the message or target. Do not delete a registration unless the payload is known to be valid.", { statusCode: 422, messageCode: "connectors.firebaseCloudMessaging.rejectedMessageTargetDoNot" });
       }
-      throw Object.assign(new Error("Firebase message request failed."), { status: response.status });
+      throw providerStatusError(response.status);
     }
     if (!receipt(result) || !result.name.startsWith(`projects/${settings.projectId}/messages/`)) {
       throw new ConnectorError("connector_response_invalid", "Firebase returned an unexpected message receipt.", { statusCode: 502, messageCode: "connectors.firebaseCloudMessaging.returnedUnexpectedMessageReceipt" });