@jskit-ai/connectors-catalog 0.1.1

package/src/server/slack.js

@@ -0,0 +1,143 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { slackDefinition } from "../shared/slack.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+function checkReply(value) {
+  if (value?.ok === true) return value;
+  if (value?.ok !== false || typeof value.error !== "string") {
+    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid response.", { statusCode: 502 });
+  }
+  if (["invalid_auth", "not_authed", "token_revoked", "token_expired", "account_inactive", "invalid_refresh_token", "invalid_grant"].includes(value.error)) {
+    throw new ConnectorError("connector_reconnect_required", "Connect this Slack account again.", { statusCode: 401 });
+  }
+  if (["missing_scope", "not_allowed_token_type", "access_denied", "no_permission", "not_in_channel", "restricted_action"].includes(value.error)) {
+    throw new ConnectorError("connector_permission_denied", "Slack denied this operation.", { statusCode: 403 });
+  }
+  if (["ratelimited", "rate_limited"].includes(value.error)) {
+    throw new ConnectorError("connector_rate_limited", "Slack's request limit was reached.", { statusCode: 429 });
+  }
+  if (["invalid_client_id", "bad_client_secret", "bad_redirect_uri"].includes(value.error)) {
+    throw new ConnectorError("connector_registration_invalid", "Check the Slack client registration and callback.", { statusCode: 422 });
+  }
+  throw new ConnectorError("connector_provider_failed", "The Slack request failed. Try again.", { statusCode: 502 });
+}
+
+async function normalizeTokenResponse(response, { settings, grantType }) {
+  if ([401, 403, 429].includes(response.status)) {
+    throw new ConnectorError(
+      { 401: "connector_reconnect_required", 403: "connector_permission_denied", 429: "connector_rate_limited" }[response.status],
+      "Slack could not authorize this request.", { statusCode: response.status }
+    );
+  }
+  let value;
+  try { value = await response.clone().json(); } catch {
+    if (!response.ok) return response;
+    throw new ConnectorError("connector_response_invalid", "Slack returned an invalid token response.", { statusCode: 502 });
+  }
+  checkReply(value);
+  if (!response.ok) return response;
+  const actor = settings.actor || "user";
+  const token = grantType === "authorization_code" && actor === "user" ? value.authed_user : value;
+  if (token?.token_type !== actor || typeof token.scope !== "string" || !/^[^\s,]+(?:,[^\s,]+)*$/u.test(token.scope)) {
+    throw new ConnectorError("connector_response_invalid", "Slack returned a token for the wrong identity or an invalid permission grant.", { statusCode: 502 });
+  }
+  // Retain exactly one identity; a response may contain both user and bot tokens.
+  return Response.json({ access_token: token.access_token, token_type: "Bearer", scope: token.scope,
+    ...(token.expires_in !== undefined ? { expires_in: token.expires_in } : {}),
+    ...(token.refresh_token !== undefined ? { refresh_token: token.refresh_token } : {})
+  });
+}
+
+const cursor = { type: "string", minLength: 1, maxLength: 4096 };
+const channel = { type: "string", required: true, validator: (value) => /^[CGD][A-Z0-9]+$/u.test(value) || "Use a conversation ID.", maxLength: 100 };
+const timestamp = { type: "string", validator: (value) => /^[0-9]+\.[0-9]+$/u.test(value) || "Use a Slack timestamp.", maxLength: 40, noTrim: true };
+const listResult = (value) => value?.ok === true && Array.isArray(value.channels) &&
+  value.channels.every((channel) => typeof channel?.id === "string" && channel.id.length > 0) &&
+  (value.response_metadata === undefined || (value.response_metadata !== null && typeof value.response_metadata === "object" &&
+    !Array.isArray(value.response_metadata) && (value.response_metadata.next_cursor === undefined || typeof value.response_metadata.next_cursor === "string")));
+const operations = {
+  "auth.test": jsonOperation("https://slack.com/api/auth.test", {}, (value) => value?.ok === true &&
+    typeof value.team_id === "string" && value.team_id.length > 0 && typeof value.user_id === "string" && value.user_id.length > 0)
+};
+for (const [name, type, permission] of [
+  ["channels.list", "public_channel", "channels:read"],
+  ["groups.list", "private_channel", "groups:read"],
+  ["directMessages.list", "im", "im:read"],
+  ["groupMessages.list", "mpim", "mpim:read"]
+]) {
+  operations[name] = {
+    ...jsonOperation(`https://slack.com/api/conversations.list?types=${type}`, {
+      limit: { type: "integer", min: 1, max: 200, defaultTo: 100 }, cursor,
+      exclude_archived: { type: "boolean", defaultTo: false }
+    }, listResult),
+    scopes: [permission]
+  };
+}
+
+for (const [name, permission] of [["channels.history", "channels:history"], ["groups.history", "groups:history"],
+  ["directMessages.history", "im:history"], ["groupMessages.history", "mpim:history"]]) {
+  operations[name] = { ...jsonOperation("https://slack.com/api/conversations.history", {
+    channel, cursor, limit: { type: "integer", min: 1, max: 15, defaultTo: 15 },
+    oldest: timestamp, latest: timestamp, inclusive: { type: "boolean", defaultTo: false }
+  }, (value) => value?.ok === true && Array.isArray(value.messages) && value.messages.length <= 15 &&
+    value.messages.every((message) => typeof message?.ts === "string" && /^[0-9]+\.[0-9]+$/u.test(message.ts)) &&
+    typeof value.has_more === "boolean" && (value.response_metadata === undefined ||
+      typeof value.response_metadata?.next_cursor === "string")), scopes: [permission] };
+}
+operations["users.info"] = { ...jsonOperation("https://slack.com/api/users.info", {
+  user: { type: "string", required: true, validator: (value) => /^[UW][A-Z0-9]+$/u.test(value) || "Use a Slack user ID.", maxLength: 100 }
+}, (value) => value?.ok === true && typeof value.user?.id === "string" && typeof value.user?.name === "string"), scopes: ["users:read"] };
+operations["messages.send"] = { ...jsonOperation("https://slack.com/api/chat.postMessage", {
+  channel, text: { type: "string", required: true, minLength: 1, maxLength: 4000, noTrim: true },
+  thread_ts: timestamp, unfurl_links: { type: "boolean", defaultTo: false },
+  unfurl_media: { type: "boolean", defaultTo: false }
+}, (value) => value?.ok === true && typeof value.channel === "string" &&
+  typeof value.ts === "string" && /^[0-9]+\.[0-9]+$/u.test(value.ts) &&
+  value.message !== null && typeof value.message === "object", "POST"), scopes: ["chat:write"] };
+
+const slackProvider = Object.freeze({
+  ...slackDefinition,
+  oauth: { issuer: "https://slack.com", authorization_endpoint: "https://slack.com/oauth/v2/authorize", token_endpoint: "https://slack.com/api/oauth.v2.access" },
+  scopeSeparator: ",",
+  authorizationScopeParameter: ({ actor = "user" } = {}) => actor === "user" ? "user_scope" : "scope",
+  normalizeTokenResponse,
+  apiOrigins: ["https://slack.com"], checkOperation: "channels.list", operations,
+  async exchange(address, options, { request }) {
+    return checkReply(await request(address, options));
+  }
+});
+// The app supplies raw bytes before body parsing and binds the expected installation.
+function verifySlackRequest({ rawBody, signature, timestamp, secret, contentType, appId, teamId, now = Date.now() }) {
+  const reject = () => { throw new ConnectorError("connector_webhook_invalid", "Invalid Slack callback.", { statusCode: 401 }); };
+  if (!(rawBody instanceof Uint8Array) || rawBody.byteLength > 1048576 ||
+    typeof secret !== "string" || !secret || typeof signature !== "string" || !/^v0=[a-f0-9]{64}$/u.test(signature) ||
+    typeof timestamp !== "string" || !/^[0-9]{1,12}$/u.test(timestamp) || !Number.isFinite(now) ||
+    Math.abs(now / 1000 - Number(timestamp)) > 300 || typeof appId !== "string" || !appId ||
+    typeof teamId !== "string" || !teamId) reject();
+  const expected = createHmac("sha256", secret).update(`v0:${timestamp}:`).update(rawBody).digest();
+  if (!timingSafeEqual(expected, Buffer.from(signature.slice(3), "hex"))) reject();
+  let payload;
+  try {
+    const body = Buffer.from(rawBody).toString("utf8");
+    const mediaType = contentType?.split(";", 1)[0].trim().toLowerCase();
+    if (mediaType === "application/json") payload = JSON.parse(body);
+    else if (mediaType === "application/x-www-form-urlencoded") {
+      const form = new URLSearchParams(body);
+      if (form.getAll("payload").length !== 1) reject();
+      payload = JSON.parse(form.get("payload"));
+    } else reject();
+  } catch { reject(); }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) reject();
+  // URL verification has no installation identity; the signature binds its app secret.
+  if (payload.type === "url_verification" && typeof payload.challenge === "string" && payload.challenge.length > 0) return payload;
+  if (payload.api_app_id !== appId || (payload.team_id ?? payload.team?.id) !== teamId) reject();
+  if (payload.type === "event_callback") {
+    if (typeof payload.event_id !== "string" || !payload.event_id || !payload.event ||
+      typeof payload.event.type !== "string") reject();
+  } else if (["block_actions", "view_submission", "view_closed", "shortcut", "message_action"].includes(payload.type)) {
+    if (typeof payload.user?.id !== "string" || !payload.user.id) reject();
+  } else reject();
+  return payload;
+}
+export { slackProvider, verifySlackRequest };

package/src/server/snowflake.js

@@ -0,0 +1,139 @@
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { snowflakeDefinition } from "../shared/snowflake.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const origin = (settings) => new URL(settings.accountUrl).origin;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const database = (value) => object(value) && typeof value.name === "string" && value.name.length > 0 && value.name.length <= 255 &&
+  ["owner", "comment", "kind", "created_on"].every((key) => value[key] == null || typeof value[key] === "string");
+const nameFilter = { type: "string", minLength: 1, maxLength: 255, noTrim: true };
+const databasesList = jsonOperation((settings) => `${origin(settings)}/api/v2/databases`, {
+  showLimit: { type: "integer", min: 1, max: 1000, defaultTo: 20 },
+  like: nameFilter, startsWith: nameFilter, fromName: nameFilter, history: { type: "boolean", defaultTo: false }
+}, (value) => Array.isArray(value) && value.every(database));
+
+const uuid = (value) => typeof value === "string" && /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/iu.test(value);
+const uuidField = { type: "string", required: true, validator: (value) => uuid(value) || "Use a Snowflake UUID." };
+const bindings = { type: "object", additionalProperties: true, validator: (value) =>
+  Object.keys(value).length <= 100 && Object.entries(value).every(([key, binding]) =>
+    /^[1-9][0-9]{0,2}$/u.test(key) && object(binding) && Object.keys(binding).every((name) => ["type", "value"].includes(name)) &&
+    ["FIXED", "REAL", "TEXT", "BINARY", "BOOLEAN", "DATE", "TIME", "TIMESTAMP_LTZ", "TIMESTAMP_NTZ", "TIMESTAMP_TZ"].includes(binding.type) &&
+    (binding.value === null || (typeof binding.value === "string" && binding.value.length <= 65536))) || "Use at most 100 numbered typed bindings." };
+const sqlResult = (value) => object(value) && ["pending", "completed", "cancelled"].includes(value.status);
+const submit = jsonOperation((settings) => `${origin(settings)}/api/v2/statements`, {
+  statement: { type: "string", required: true, minLength: 1, maxLength: 65536, noTrim: true },
+  requestId: uuidField, bindings, timeout: { type: "integer", min: 1, max: 3600, defaultTo: 60 }
+}, sqlResult, "POST");
+const operations = { "databases.list": databasesList,
+  "statements.submit": { ...submit, request(input, settings) {
+    const request = submit.request(input, settings);
+    const { requestId, ...body } = request.body;
+    for (const name of ["warehouse", "database", "schema", "role"]) if (settings[name]) body[name] = settings[name];
+    body.parameters = { multi_statement_count: "1" };
+    return { ...request, url: `${request.url}?async=true&requestId=${requestId}`, body };
+  } }
+};
+for (const [operation, cancel] of [["statements.get", false], ["statements.cancel", true]]) {
+  const base = jsonOperation((settings) => `${origin(settings)}/api/v2/statements`, {
+    handle: uuidField, ...(!cancel ? { partition: { type: "integer", min: 0, max: 100000 } } : {})
+  }, sqlResult, "POST");
+  operations[operation] = { ...base, request(input, settings) {
+    const { url, body } = base.request(input, settings);
+    return { method: cancel ? "POST" : "GET", url: `${url}/${body.handle}${cancel ? "/cancel" : body.partition === undefined ? "" : `?partition=${body.partition}`}`,
+      ...(cancel ? { body: {} } : {}) };
+  } };
+}
+for (const action of ["create", "resize", "resume", "suspend", "delete"]) {
+  const fields = { name: { ...nameFilter, required: true }, requestId: uuidField };
+  if (["create", "resize"].includes(action)) fields.size = { type: "string", required: true,
+    enum: ["XSMALL", "SMALL", "MEDIUM", "LARGE", "XLARGE", "XXLARGE", "XXXLARGE", "X4LARGE", "X5LARGE", "X6LARGE"] };
+  const base = jsonOperation((settings) => `${origin(settings)}/api/v2/statements`, fields, sqlResult, "POST");
+  operations[`warehouses.${action}`] = { ...base, request(input, settings) {
+    const { body } = base.request(input, settings);
+    const name = `"${body.name.replaceAll('"', '""')}"`;
+    const statement = action === "create"
+      ? `CREATE WAREHOUSE ${name} WAREHOUSE_SIZE = ${body.size} INITIALLY_SUSPENDED = TRUE AUTO_SUSPEND = 60 AUTO_RESUME = FALSE`
+      : action === "resize" ? `ALTER WAREHOUSE ${name} SET WAREHOUSE_SIZE = ${body.size}`
+      : action === "delete" ? `DROP WAREHOUSE ${name}`
+      : `ALTER WAREHOUSE ${name} ${action === "resume" ? "RESUME IF SUSPENDED" : "SUSPEND"}`;
+    return operations["statements.submit"].request({ statement, requestId: body.requestId }, settings);
+  } };
+}
+for (const [name, operation] of Object.entries(operations)) {
+  operations[name] = { ...operation, request(input, settings) {
+    return { ...operation.request(input, settings), headers: { "X-Snowflake-Authorization-Token-Type": "OAUTH",
+      "User-Agent": "jskit-connectors/0.1", ...(settings.role ? { "X-Snowflake-Role": `"${settings.role}"` } : {}) } };
+  } };
+}
+
+const snowflakeProvider = Object.freeze({
+  ...snowflakeDefinition,
+  oauth: (settings) => ({ issuer: origin(settings), authorization_endpoint: `${origin(settings)}/oauth/authorize`,
+    token_endpoint: `${origin(settings)}/oauth/token-request` }),
+  apiOrigins: (settings) => [origin(settings)], checkOperation: "databases.list", scopesInAuthorizationResponse: true,
+  async normalizeTokenResponse(response) {
+    if (response.ok) {
+      let value;
+      try { value = await response.clone().json(); } catch { /* rejected below */ }
+      if (!Number.isSafeInteger(value?.expires_in) || value.expires_in <= 0 ||
+        (value.scope !== undefined && (typeof value.scope !== "string" || !/^[^\s]+(?: [^\s]+)*$/u.test(value.scope))) ||
+        (value.refresh_token !== undefined && (typeof value.refresh_token !== "string" || !value.refresh_token.trim()))) {
+        throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid token grant.", { statusCode: 502 });
+      }
+    }
+    return response;
+  },
+  operations,
+  async exchange(address, options, { fetchImpl }) {
+    const response = await fetchImpl(address, { ...options, credentials: "omit",
+      ...(options.body !== undefined ? { body: JSON.stringify(options.body), headers: { ...options.headers, "Content-Type": "application/json" } } : {}) });
+    const url = new URL(address);
+    const sql = url.pathname.startsWith("/api/v2/statements");
+    if (sql && response.status === 422) throw new ConnectorError("connector_operation_rejected", "Snowflake rejected the statement. Inspect query history with the authorized role.", { statusCode: 422 });
+    if (!response.ok) throw Object.assign(new Error("Snowflake request failed."), { status: response.status });
+    const reader = response.body?.getReader();
+    const chunks = [];
+    let size = 0;
+    if (reader) try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > 16 * 1024 * 1024) {
+          await reader.cancel();
+          throw new ConnectorError("connector_response_too_large", "Snowflake response exceeds 16 MiB. Reduce the query result or use a native streaming client.", { statusCode: 413 });
+        }
+        chunks.push(value);
+      }
+    } finally { reader.releaseLock(); }
+    let result;
+    try { result = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { /* rejected below */ }
+    if (sql) {
+      const reject = () => { throw new ConnectorError("connector_response_invalid", "Snowflake returned an invalid statement response.", { statusCode: 502 }); };
+      if (!object(result)) reject();
+      const requestedHandle = url.pathname.split("/")[4];
+      const handle = result.statementHandle ?? requestedHandle;
+      if (!uuid(handle) || (requestedHandle && requestedHandle !== handle)) reject();
+      if (response.status === 202 && result.code === "333334") return { status: "pending", handle };
+      if (response.status !== 200) reject();
+      if (url.pathname.endsWith("/cancel")) {
+        if (result.code !== "000604") reject();
+        return { status: "cancelled", handle };
+      }
+      if (result.code !== undefined && !["090001", "391908"].includes(result.code)) reject();
+      if (!Array.isArray(result.data) || !result.data.every((row) => Array.isArray(row) && row.every((cell) => cell === null || typeof cell === "string"))) reject();
+      const metadata = result.resultSetMetaData;
+      if (metadata !== undefined && (!object(metadata) || !Array.isArray(metadata.rowType) ||
+        !metadata.rowType.every((column) => object(column) && typeof column.name === "string" && typeof column.type === "string") ||
+        !result.data.every((row) => row.length === metadata.rowType.length))) reject();
+      if (metadata === undefined && !url.searchParams.has("partition")) reject();
+      return { status: "completed", handle, data: result.data, ...(metadata ? { metadata } : {}),
+        ...(url.searchParams.has("partition") ? { partition: Number(url.searchParams.get("partition")) } : {}) };
+    }
+    if (response.status !== 200 || !Array.isArray(result) || result.length > Number(url.searchParams.get("showLimit"))) {
+      throw new ConnectorError("connector_response_invalid", "Snowflake returned an unexpected database page.", { statusCode: 502 });
+    }
+    return result;
+  }
+});
+export { snowflakeProvider };

package/src/server/storyblok.js

@@ -0,0 +1,49 @@
+import { storyblokDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const origins = {
+  eu: "https://api.storyblok.com", us: "https://api-us.storyblok.com",
+  ca: "https://api-ca.storyblok.com", ap: "https://api-ap.storyblok.com",
+  cn: "https://app.storyblokchina.cn"
+};
+const contentFields = {
+  version: { type: "string", enum: ["published", "draft"], defaultTo: "published" },
+  language: { type: "string", maxLength: 64 },
+  cv: { type: "integer", min: 0 },
+  resolve_relations: { type: "string", minLength: 1, maxLength: 2048 },
+  resolve_links: { type: "string", enum: ["url", "link", "story"] },
+  resolve_assets: { type: "integer", enum: [0, 1] }
+};
+const story = (value) => Number.isSafeInteger(value?.id) && value.id > 0 &&
+  value.content !== null && typeof value.content === "object" && !Array.isArray(value.content);
+const getStory = jsonOperation((settings) => `${origins[settings.region]}/v2/cdn/stories`, {
+  ...contentFields,
+  id: { type: "string", required: true, minLength: 1, maxLength: 1024,
+    validator: (value) => value.split("/").every((part) => part && part !== "." && part !== "..") || "Use a story ID or full slug without empty or relative path segments." },
+  find_by: { type: "string", enum: ["uuid"] }
+}, (result) => story(result?.story), "POST");
+const storyblokProvider = Object.freeze({
+  ...storyblokDefinition, apiOrigins: Object.values(origins),
+  apiKey: { queryParameter: "token" },
+  checkOperation: "space.read",
+  operations: {
+    "space.read": jsonOperation((settings) => `${origins[settings.region]}/v2/cdn/spaces/me`, {},
+      (result) => Number.isInteger(result?.space?.id) && typeof result.space.name === "string" &&
+        Array.isArray(result.space.language_codes)),
+    "stories.list": jsonOperation((settings) => `${origins[settings.region]}/v2/cdn/stories`, {
+      ...contentFields,
+      page: { type: "integer", min: 1, max: 2147483647, defaultTo: 1 },
+      per_page: { type: "integer", min: 1, max: 100, defaultTo: 25 },
+      starts_with: { type: "string", maxLength: 1024 },
+      search_term: { type: "string", maxLength: 1024 },
+      content_type: { type: "string", maxLength: 255 },
+    }, (result) => Array.isArray(result?.stories) && result.stories.every(story)),
+    "stories.get": { ...getStory, request(input, settings) {
+      const { url, body: { id, ...query } } = getStory.request(input, settings);
+      const destination = new URL(`${url}/${id.split("/").map(encodeURIComponent).join("/")}`);
+      for (const [key, value] of Object.entries(query)) destination.searchParams.set(key, String(value));
+      return { method: "GET", url: destination.href };
+    } }
+  }
+});
+export { storyblokProvider };

package/src/server/stripe.js

@@ -0,0 +1,13 @@
+import { stripeDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const stripeProvider = Object.freeze({
+  ...stripeDefinition, apiOrigins: ["https://api.stripe.com"],
+  apiKey: { headers: (key) => ({ Authorization: `Bearer ${key}` }) },
+  checkOperation: "balance.read",
+  operations: {
+    "balance.read": jsonOperation("https://api.stripe.com/v1/balance", {},
+      (result) => result?.object === "balance" && Array.isArray(result.available) && Array.isArray(result.pending) && typeof result.livemode === "boolean")
+  }
+});
+export { stripeProvider };

package/src/server/supabase.js

@@ -0,0 +1,13 @@
+import { supabaseDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const supabaseProvider = Object.freeze({
+  ...supabaseDefinition, apiOrigins: ["https://api.supabase.com"],
+  apiKey: { headers: (key) => ({ Authorization: `Bearer ${key}` }) },
+  checkOperation: "projects.list",
+  operations: {
+    "projects.list": jsonOperation("https://api.supabase.com/v1/projects", {},
+      (result) => Array.isArray(result) && result.every((item) => typeof item?.id === "string" && typeof item.name === "string"))
+  }
+});
+export { supabaseProvider };

package/src/server/tally.js

@@ -0,0 +1,78 @@
+import { createSchema } from "json-rest-schema";
+import { validateSchemaPayload } from "@jskit-ai/kernel/shared/validators";
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { tallyDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const formIdField = { type: "string", required: true, noTrim: true,
+  validator: (value) => /^[A-Za-z0-9_-]{1,128}$/u.test(value) || "Enter a Tally form ID, not a URL." };
+const blocksField = { type: "array", validator: (value) => value.length <= 500 &&
+  value.every((block) => block && typeof block === "object" && !Array.isArray(block) && typeof block.type === "string") || "Supply up to 500 native Tally block objects." };
+const statusField = { type: "string", enum: ["BLANK", "DRAFT", "PUBLISHED"] };
+const formResult = (result) => typeof result?.id === "string" && typeof result.name === "string" &&
+  ["BLANK", "DRAFT", "PUBLISHED"].includes(result.status);
+const formGetSchema = createSchema({ formId: formIdField });
+const formUpdateSchema = createSchema({ formId: formIdField,
+  name: { type: "string", maxLength: 1000 }, status: statusField, blocks: blocksField });
+
+const submissionsSchema = createSchema({
+  formId: { type: "string", required: true, noTrim: true,
+    validator: (value) => /^[A-Za-z0-9_-]{1,128}$/u.test(value) || "Enter a Tally form ID, not a URL." },
+  page: { type: "integer", min: 1, defaultTo: 1 },
+  limit: { type: "integer", min: 1, max: 500, defaultTo: 50 },
+  filter: { type: "string", enum: ["all", "completed", "partial"], defaultTo: "completed" },
+  afterId: { type: "string", noTrim: true,
+    validator: (value) => /^[A-Za-z0-9_-]{1,128}$/u.test(value) || "Use the returned submission ID." }
+});
+
+const tallyProvider = Object.freeze({
+  ...tallyDefinition, apiOrigins: ["https://api.tally.so"],
+  apiKey: { headers: (key) => ({ Authorization: `Bearer ${key}`, "tally-version": "2025-02-01" }) },
+  checkOperation: "forms.list",
+  operations: {
+    "forms.create": jsonOperation("https://api.tally.so/forms", {
+      workspaceId: { ...formIdField, required: false },
+      templateId: { ...formIdField, required: false },
+      folderId: { ...formIdField, required: false },
+      status: { ...statusField, defaultTo: "DRAFT" },
+      blocks: { ...blocksField, required: true }
+    }, formResult, "POST"),
+    "forms.get": {
+      scopes: [],
+      request(input) {
+        const { formId } = validateSchemaPayload({ schema: formGetSchema, mode: "replace" }, input, { statusCode: 422 });
+        return { method: "GET", url: `https://api.tally.so/forms/${formId}` };
+      },
+      validateResult: (result) => formResult(result) && Array.isArray(result.blocks)
+    },
+    "forms.update": {
+      scopes: [],
+      request(input) {
+        const { formId, ...body } = validateSchemaPayload({ schema: formUpdateSchema, mode: "replace" }, input, { statusCode: 422 });
+        if (!Object.keys(body).length) throw new ConnectorError("connector_input_invalid", "Choose a name, status or block change.", { statusCode: 422 });
+        return { method: "PATCH", url: `https://api.tally.so/forms/${formId}`, body };
+      },
+      validateResult: formResult
+    },
+    "submissions.list": {
+      scopes: [],
+      request(input) {
+        const { formId, ...values } = validateSchemaPayload({ schema: submissionsSchema, mode: "replace" }, input, { statusCode: 422 });
+        const url = new URL(`https://api.tally.so/forms/${formId}/submissions`);
+        for (const [name, value] of Object.entries(values)) url.searchParams.set(name, String(value));
+        return { method: "GET", url: url.href };
+      },
+      validateResult: (result) => Number.isSafeInteger(result?.page) && result.page >= 1 &&
+        Number.isSafeInteger(result.limit) && result.limit >= 1 && result.limit <= 500 &&
+        typeof result.hasMore === "boolean" && Array.isArray(result.questions) &&
+        Array.isArray(result.submissions) && result.submissions.every((submission) =>
+          typeof submission?.id === "string" && typeof submission.formId === "string" &&
+          typeof submission.isCompleted === "boolean" && Array.isArray(submission.responses))
+    },
+    "forms.list": jsonOperation("https://api.tally.so/forms", {
+      limit: { type: "integer", min: 1, max: 500, defaultTo: 50 },
+      page: { type: "integer", min: 1, defaultTo: 1 }
+    }, (result) => Array.isArray(result?.items) && Number.isInteger(result.total) && typeof result.hasMore === "boolean")
+  }
+});
+export { tallyProvider };

package/src/server/telegram.js

@@ -0,0 +1,55 @@
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { telegramDefinition } from "../shared/tokens.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+function telegramResult(response, validate) {
+  if (response?.ok === false) {
+    const error = new Error("Telegram rejected the operation.");
+    error.status = response.error_code;
+    throw error;
+  }
+  return response?.ok === true && validate(response.result);
+}
+
+const chatIdField = { type: "string", required: true, noTrim: true,
+  validator: (value) => /^-?[1-9][0-9]{0,15}$/u.test(value) || /^@[A-Za-z][A-Za-z0-9_]{4,31}$/u.test(value) || "Enter a chat ID as a decimal string or @username." };
+
+const telegramProvider = Object.freeze({
+  ...telegramDefinition, requestTimeoutMs: 30000,
+  apiOrigins: ["https://api.telegram.org"],
+  apiKey: { pathPrefix(key) {
+    if (!/^\d+:[A-Za-z0-9_-]+$/.test(key)) {
+      throw new ConnectorError("connector_binding_invalid", "Configure a Telegram bot token in the referenced environment variable.");
+    }
+    return `/bot${key}`;
+  } },
+  checkOperation: "profile.read",
+  operations: {
+    "messages.send": jsonOperation("https://api.telegram.org/sendMessage", {
+      chat_id: chatIdField,
+      text: { type: "string", required: true, noTrim: true, minLength: 1, maxLength: 4096 },
+      message_thread_id: { type: "integer", min: 1 },
+      disable_notification: { type: "boolean", defaultTo: false },
+      protect_content: { type: "boolean", defaultTo: false }
+    }, (response) => telegramResult(response, (message) => Number.isSafeInteger(message?.message_id) &&
+      Number.isSafeInteger(message.chat?.id) && typeof message.text === "string"), "POST"),
+    "chats.action": jsonOperation("https://api.telegram.org/sendChatAction", {
+      chat_id: chatIdField, message_thread_id: { type: "integer", min: 1 },
+      action: { type: "string", required: true, enum: ["typing", "upload_photo", "record_video", "upload_video", "record_voice", "upload_voice", "upload_document", "choose_sticker", "find_location", "record_video_note", "upload_video_note"] }
+    }, (response) => telegramResult(response, (value) => value === true), "POST"),
+    "updates.poll": jsonOperation("https://api.telegram.org/getUpdates", {
+      offset: { type: "integer", min: 0 },
+      limit: { type: "integer", min: 1, max: 100, defaultTo: 100 },
+      timeout: { type: "integer", min: 0, max: 20, defaultTo: 20 },
+      allowed_updates: { type: "array", defaultTo: ["message"],
+        validator: (value) => value.length > 0 && value.length <= 4 && value.every((kind) => ["message", "edited_message", "channel_post", "edited_channel_post"].includes(kind)) || "Choose supported message update types explicitly." }
+    }, (response) => telegramResult(response, (updates) => Array.isArray(updates) &&
+      updates.every((update) => Number.isSafeInteger(update?.update_id) && update.update_id >= 0)), "POST"),
+    "profile.read": jsonOperation("https://api.telegram.org/getMe", {}, (response) => telegramResult(response,
+      (bot) => Number.isSafeInteger(bot?.id) && bot.id > 0 && bot.is_bot === true && typeof bot.first_name === "string")),
+    "webhook.read": jsonOperation("https://api.telegram.org/getWebhookInfo", {}, (response) => telegramResult(response,
+      (webhook) => typeof webhook?.url === "string" && typeof webhook.has_custom_certificate === "boolean" &&
+        Number.isInteger(webhook.pending_update_count) && webhook.pending_update_count >= 0))
+  }
+});
+export { telegramProvider };

package/src/server/tiktok.js

@@ -0,0 +1,86 @@
+import { ConnectorError } from "@jskit-ai/connectors-core/server";
+import { tiktokDefinition } from "../shared/tiktok.js";
+import { jsonOperation } from "./jsonOperation.js";
+
+const textId = (value) => typeof value === "string" && value.length > 0 && value.length <= 1024 && !/[\p{Cc}]/u.test(value);
+const count = (value) => Number.isSafeInteger(value) && value >= 0;
+
+function checkReply(value) {
+  const code = value?.error?.code ?? value?.code;
+  if (code === "ok") return value;
+  if (typeof code !== "string" || !code) throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502 });
+  if (code === "access_token_invalid") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401 });
+  if (["scope_not_authorized", "scope_permission_missed"].includes(code)) {
+    throw new ConnectorError("connector_scope_missing", "Connect TikTok with the permission required for this operation.", { statusCode: 403 });
+  }
+  if (code === "rate_limit_exceeded") throw new ConnectorError("connector_rate_limited", "TikTok's request limit was reached.", { statusCode: 429 });
+  throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502 });
+}
+
+function profileOperation(fields, scope, validateUser) {
+  return { ...jsonOperation(`https://open.tiktokapis.com/v2/user/info/?fields=${fields.join(",")}`, {},
+    (value) => value?.error?.code === "ok" && validateUser(value.data?.user)), scopes: [scope] };
+}
+
+const tiktokProvider = Object.freeze({
+  ...tiktokDefinition,
+  oauth: { issuer: "https://www.tiktok.com", authorization_endpoint: "https://www.tiktok.com/v2/auth/authorize/", token_endpoint: "https://open.tiktokapis.com/v2/oauth/token/" },
+  oauthClientIdParameter: "client_key", scopeSeparator: ",",
+  validateCallbackUrl: (value) => value.startsWith("https://") && value.length < 512,
+  async normalizeTokenResponse(response) {
+    let value;
+    try { value = await response.clone().json(); } catch {
+      if (!response.ok) return response;
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid token response.", { statusCode: 502 });
+    }
+    if (!response.ok) return response;
+    if (value?.error) {
+      if (value.error === "invalid_grant") throw new ConnectorError("connector_reconnect_required", "Connect this TikTok account again.", { statusCode: 401 });
+      throw new ConnectorError("connector_provider_failed", "TikTok could not authorize this connection.", { statusCode: 502 });
+    }
+    if (!textId(value?.open_id) || !Number.isSafeInteger(value.expires_in) || value.expires_in <= 0 ||
+      !Number.isSafeInteger(value.refresh_expires_in) || value.refresh_expires_in <= 0 || !textId(value.refresh_token) ||
+      typeof value.scope !== "string" || !/^[^\s,]+(?:,[^\s,]+)*$/u.test(value.scope)) {
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid permission grant.", { statusCode: 502 });
+    }
+    const scopes = value.scope.split(",");
+    if (new Set(scopes).size !== scopes.length) throw new ConnectorError("connector_response_invalid", "TikTok returned duplicate permissions.", { statusCode: 502 });
+    if (!scopes.includes("user.info.basic")) throw new ConnectorError("connector_scope_missing", "Connect TikTok with basic profile permission.", { statusCode: 403 });
+    return response;
+  },
+  apiOrigins: ["https://open.tiktokapis.com"], checkOperation: "profile.read",
+  operations: {
+    "profile.read": profileOperation(["open_id", "display_name", "avatar_url"], "user.info.basic", (user) =>
+      textId(user?.open_id) && typeof user.display_name === "string" && typeof user.avatar_url === "string"),
+    "profile.extended": profileOperation(["username", "bio_description", "profile_deep_link", "is_verified"], "user.info.profile", (user) =>
+      ["username", "bio_description", "profile_deep_link"].every((field) => typeof user?.[field] === "string") && typeof user?.is_verified === "boolean"),
+    "profile.stats": profileOperation(["follower_count", "following_count", "likes_count", "video_count"], "user.info.stats", (user) =>
+      ["follower_count", "following_count", "likes_count", "video_count"].every((field) => count(user?.[field]))),
+    "videos.list": {
+      ...jsonOperation("https://open.tiktokapis.com/v2/video/list/?fields=id,title,cover_image_url", {
+        max_count: { type: "integer", min: 1, max: 20, defaultTo: 10 },
+        cursor: { type: "integer", min: 0, max: Number.MAX_SAFE_INTEGER }
+      }, (value) => value?.error?.code === "ok" && Array.isArray(value.data?.videos) && value.data.videos.length <= 20 &&
+        value.data.videos.every((video) => textId(video?.id) && typeof video.title === "string" && typeof video.cover_image_url === "string") &&
+        typeof value.data.has_more === "boolean" && count(value.data.cursor), "POST"),
+      scopes: ["video.list"]
+    }
+  },
+  async exchange(address, options, { fetchImpl }) {
+    const response = await fetchImpl(address, { ...options, credentials: "omit",
+      headers: { ...options.headers, ...(options.body ? { "Content-Type": "application/json" } : {}) },
+      ...(options.body ? { body: JSON.stringify(options.body) } : {}) });
+    let value;
+    try { value = await response.json(); } catch {
+      throw new ConnectorError("connector_response_invalid", "TikTok returned an invalid response.", { statusCode: 502 });
+    }
+    checkReply(value);
+    if (!response.ok) throw new ConnectorError("connector_provider_failed", "TikTok could not complete the request.", { statusCode: 502 });
+    if (options.body?.max_count !== undefined && value.data?.videos?.length > options.body.max_count) {
+      throw new ConnectorError("connector_response_invalid", "TikTok returned too many videos.", { statusCode: 502 });
+    }
+    return value;
+  }
+});
+
+export { tiktokProvider };