AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents
TypeScript ai-agentai-agent-toolsai-agentsai-agents-frameworkmcpmcp-servermcp-toolsmcpsn8n-alternativeno-code-automationworkflowworkflow-automationworkflows
import { httpClient, HttpMethod, HttpResponse, QueryParams } from '@activepieces/pieces-common';
const REQUEST_TIMEOUT_MS = 30_000;
const MAX_RATE_LIMIT_RETRIES = 2;
const MAX_RETRY_WAIT_MS = 30_000;
const LOCAL_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
let verifiedTlsAgent: Promise<unknown> | undefined;
export class MatrixApiError extends Error {
constructor(
message: string,
public readonly status: number,
public readonly errcode: string | undefined,
public readonly responseBody: unknown,
) {
super(message);
this.name = 'MatrixApiError';
}
}
function isRecord(value: unknown): value is Record<string, unknown> {
return value !== null && typeof value === 'object' && !Array.isArray(value);
}
function normalizeHomeserver(raw: unknown): string {
const text = typeof raw === 'string' ? raw.trim() : '';
if (!text) {
throw new Error('The Matrix connection has no Home Server URL.');
}
const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`;
let parsed: URL;
try {
parsed = new URL(withScheme);
} catch {
throw new Error('The Home Server is not a valid URL. Use an address like https://matrix-client.matrix.org.');
}
if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
throw new Error('The Home Server URL must start with https://.');
}
if (parsed.protocol === 'http:' && !LOCAL_HOSTS.includes(parsed.hostname)) {
throw new Error('The Home Server URL must use https:// (http:// is only allowed for localhost).');
}
if (parsed.username || parsed.password) {
throw new Error('The Home Server URL must not contain a username or password.');
}
if (parsed.hash.startsWith('#/')) {
throw new Error(
'The Home Server looks like a web app link (it contains #/). Use the homeserver address from Element > Settings > Help & About, e.g. https://matrix-client.matrix.org.',
);
}
if (parsed.search || parsed.hash || text.includes('?') || text.includes('#')) {
throw new Error('The Home Server URL must not contain a query string or fragment.');
}
const path = parsed.pathname.replace(/\/+$/, '');
if (/(^|[/\\])\.\.?([/\\?#]|$)/.test(text.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '/')) || path.split('/').some((part) => part === '..' || part === '.')) {
throw new Error('The Home Server URL must not contain relative path segments.');
}
return `${parsed.origin}${path}`;
}
function isSameOrigin({ url, baseUrl }: { url: string; baseUrl: string }): boolean {
let parsed: URL;
try {
parsed = new URL(url);
} catch {
return false;
}
if (parsed.username || parsed.password) return false;
const base = new URL(baseUrl);
if (parsed.origin !== base.origin) return false;
const basePath = base.pathname.replace(/\/+$/, '');
if (basePath === '') return true;
return parsed.pathname === basePath || parsed.pathname.startsWith(`${basePath}/`);
}
function accessTokenOf(auth: MatrixAuthValue): string {
const token = typeof auth.access_token === 'string' ? auth.access_token.trim() : '';
if (!token) {
throw new Error('The Matrix connection has no Access Token.');
}
return token;
}
function hintFor({ status, errcode }: { status: number; errcode: string | undefined }): string {
if (errcode === 'M_UNKNOWN_TOKEN' || status === 401) return ' The access token is invalid or was logged out; reconnect Matrix.';
if (errcode === 'M_FORBIDDEN') return ' Check the room membership and power levels of this account and the target user.';
if (errcode === 'M_NOT_FOUND' || status === 404) return ' Check the room, event or user ID.';
if (errcode === 'M_LIMIT_EXCEEDED' || status === 429) return ' The homeserver is rate limiting this account; try again later.';
if (errcode === 'M_UNRECOGNIZED') return ' The homeserver does not support this endpoint.';
return '';
}
function toApiError({ status, body }: { status: number; body: unknown }): MatrixApiError {
const errcode = isRecord(body) && typeof body['errcode'] === 'string' ? body['errcode'] : undefined;
let text = 'request failed';
if (status >= 300 && status < 400) text = 'unexpected redirect';
else if (isRecord(body) && typeof body['error'] === 'string' && body['error'].trim()) text = body['error'].trim().replace(/\.+$/, '');
else if (typeof body === 'string' && body.trim()) text = body.trim().slice(0, 300);
const code = errcode ? ` ${errcode}` : '';
return new MatrixApiError(`Matrix API error (${status}${code}): ${text}.${hintFor({ status, errcode })}`, status, errcode, body);
}
function verifiedTls(): Promise<unknown> {
verifiedTlsAgent ??= import('undici').then(({ Agent }) => new Agent({ connect: { rejectUnauthorized: true } }));
return verifiedTlsAgent;
}
function failureOf(error: unknown): { status: number; body: unknown; headers: unknown } | null {
if (error === null || typeof error !== 'object') return null;
const response = Reflect.get(error, 'response');
if (!isRecord(response)) return null;
const status = response['status'];
return typeof status === 'number' ? { status, body: response['body'], headers: response['headers'] } : null;
}
function retryWaitMs({ body, headers }: { body: unknown; headers: unknown }): number {
let wait = 1000;
if (isRecord(body) && typeof body['retry_after_ms'] === 'number') {
wait = body['retry_after_ms'];
} else if (isRecord(headers)) {
const header = headers['retry-after'];
const seconds = Number(Array.isArray(header) ? header[0] : header);
if (Number.isFinite(seconds)) wait = seconds * 1000;
}
return Math.min(Math.max(wait, 0), MAX_RETRY_WAIT_MS);
}
function buildQuery(query?: Record<string, string | number | boolean | undefined>): QueryParams {
return Object.fromEntries(
Object.entries(query ?? {})
.filter(([, value]) => value !== undefined)
.map(([key, value]) => [key, String(value)]),
);
}
async function sendOnce({ baseUrl, token, method, path, query, body }: SendOnceParams): Promise<{ status: number; body: unknown; headers: unknown }> {
const headers: Record<string, string> = { accept: 'application/json', authorization: `Bearer ${token}` };
if (body !== undefined) headers['content-type'] = 'application/json';
const dispatcher = await verifiedTls();
try {
const response: HttpResponse = await httpClient.sendRequest(
{
method,
url: `${baseUrl}${path}`,
headers,
queryParams: buildQuery(query),
body,
timeout: REQUEST_TIMEOUT_MS,
followRedirects: false,
},
{ dispatcher },
);
return { status: response.status, body: response.body, headers: response.headers };
} catch (error) {
const failure = failureOf(error);
if (!failure) throw error;
return failure;
}
}
async function request({ auth, method, path, query, body }: MatrixRequest): Promise<unknown> {
const baseUrl = normalizeHomeserver(auth.base_url);
const token = accessTokenOf(auth);
for (let attempt = 0; ; attempt++) {
const result = await sendOnce({ baseUrl, token, method, path, query, body });
if (result.status >= 200 && result.status < 300) {
return result.body;
}
if (result.status === 429 && attempt < MAX_RATE_LIMIT_RETRIES) {
await new Promise((resolve) => setTimeout(resolve, retryWaitMs(result)));
continue;
}
throw toApiError(result);
}
}
function arrayOf(value: unknown): unknown[] {
return Array.isArray(value) ? value : [];
}
function stringOr(value: unknown): string | null {
return typeof value === 'string' ? value : null;
}
function optionalText(value: unknown): string | undefined {
if (typeof value !== 'string') return undefined;
const text = value.trim();
return text === '' ? undefined : text;
}
function requiredText({ value, label }: { value: unknown; label: string }): string {
const text = optionalText(value);
if (text === undefined) throw new Error(`${label} is required.`);
return text;
}
function messageText({ value, label }: { value: unknown; label: string }): string {
if (typeof value !== 'string' || value.trim() === '') throw new Error(`${label} is required.`);
return value;
}
function isServerName(value: string): boolean {
return /^(?:[A-Za-z0-9.-]+|\[[0-9A-Fa-f:.]+\])(:\d{1,5})?$/.test(value);
}
function parseLimit({ value, label, min, max, fallback }: { value: unknown; label: string; min: number; max: number; fallback: number }): number {
if (value === undefined || value === null || value === '') return fallback;
const parsed = typeof value === 'string' ? Number(value.trim()) : value;
if (typeof parsed !== 'number' || !Number.isInteger(parsed) || parsed < min || parsed > max) {
throw new Error(`${label} must be a whole number from ${min} to ${max}.`);
}
return parsed;
}
function stringList(value: unknown): string[] {
if (Array.isArray(value)) {
return value.flatMap((item) => (typeof item === 'string' ? item.split(',') : [])).map((item) => item.trim()).filter((item) => item !== '');
}
if (typeof value === 'string') {
return value.split(',').map((item) => item.trim()).filter((item) => item !== '');
}
return [];
}
export const matrixClient = {
request,
normalizeHomeserver,
isSameOrigin,
accessTokenOf,
isRecord,
arrayOf,
stringOr,
optionalText,
requiredText,
messageText,
isServerName,
parseLimit,
stringList,
retryWaitMs,
};
type SendOnceParams = {
baseUrl: string;
token: string;
method: HttpMethod;
path: string;
query?: Record<string, string | number | boolean | undefined>;
body?: unknown;
};
export type MatrixAuthValue = {
base_url: string;
access_token: string;
};
export type MatrixRequest = {
auth: MatrixAuthValue;
method: HttpMethod;
path: string;
query?: Record<string, string | number | boolean | undefined>;
body?: unknown;
};