feat: add ZoomInfo plugin

packages/zoominfo/client.ts

@@ -0,0 +1,59 @@
+import type { ApiRequestOptions, OpenAPIConfig } from 'corsair/http';
+import { request } from 'corsair/http';
+
+export class ZoominfoAPIError extends Error {
+	constructor(
+		message: string,
+		public readonly code?: string,
+	) {
+		super(message);
+		this.name = 'ZoominfoAPIError';
+	}
+}
+
+// TODO: Update with your API base URL
+const ZOOMINFO_API_BASE = 'https://api.zoominfo.com/gtm/data/v1';
+
+export async function makeZoominfoRequest<T>(
+	endpoint: string,
+	apiKey: string,
+	options: {
+		method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+		body?: Record<string, unknown>;
+		query?: Record<string, string | number | boolean | undefined>;
+	} = {},
+): Promise<T> {
+	const { method = 'GET', body, query } = options;
+
+	const config: OpenAPIConfig = {
+		BASE: ZOOMINFO_API_BASE,
+		VERSION: '1.0.0',
+		WITH_CREDENTIALS: false,
+		CREDENTIALS: 'omit',
+		TOKEN: apiKey,
+		HEADERS: {
+			'Content-Type': 'application/json',
+			Authorization: `Bearer ${apiKey}`,
+		},
+	};
+
+	const requestOptions: ApiRequestOptions = {
+		method,
+		url: endpoint,
+		body:
+			method === 'POST' || method === 'PUT' || method === 'PATCH'
+				? body
+				: undefined,
+		mediaType: 'application/json; charset=utf-8',
+		query: method === 'GET' ? query : undefined,
+	};
+
+	try {
+		return await request<T>(config, requestOptions);
+	} catch (error) {
+		if (error instanceof Error) {
+			throw new ZoominfoAPIError(error.message);
+		}
+		throw new ZoominfoAPIError('Unknown error');
+	}
+}

packages/zoominfo/endpoints/index.ts

@@ -0,0 +1,7 @@
+import { searchCompanies } from './search-companies';
+
+export const Zoominfo = {
+	searchCompanies,
+};
+
+export * from './types';

packages/zoominfo/endpoints/search-companies.ts

@@ -0,0 +1,31 @@
+import { logEventFromContext } from 'corsair/core';
+import type { ZoominfoContext } from '..';
+import { makeZoominfoRequest } from '../client';
+import type { ZoominfoEndpointOutputs } from './types';
+
+export const searchCompanies = async (
+	ctx: ZoominfoContext,
+	input: {
+		companyName?: string;
+		industry?: string;
+		location?: string;
+		employeeCountMin?: number;
+		employeeCountMax?: number;
+	},
+): Promise<ZoominfoEndpointOutputs['searchCompanies']> => {
+	const response = await makeZoominfoRequest<
+		ZoominfoEndpointOutputs['searchCompanies']
+	>('contacts/search', ctx.key, {
+		method: 'POST',
+		body: { ...input },
+	});
+
+	await logEventFromContext(
+		ctx,
+		'zoominfo.searchCompanies',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};

packages/zoominfo/endpoints/types.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+const SearchCompaniesInputSchema = z.object({
+	companyName: z.string().optional(),
+	industry: z.string().optional(),
+	location: z.string().optional(),
+	employeeCountMin: z.number().optional(),
+	employeeCountMax: z.number().optional(),
+});
+
+export type SearchCompaniesInput = z.infer<typeof SearchCompaniesInputSchema>;
+
+const SearchCompaniesResponseSchema = z.object({
+	companies: z.array(
+		z.object({
+			id: z.string(),
+			name: z.string(),
+			industry: z.string().optional(),
+			employeeCount: z.number().optional(),
+			website: z.string().optional(),
+		}),
+	),
+});
+
+export type SearchCompaniesResponse = z.infer<
+	typeof SearchCompaniesResponseSchema
+>;
+
+export type ZoominfoEndpointInputs = {
+	searchCompanies: SearchCompaniesInput;
+};
+
+export type ZoominfoEndpointOutputs = {
+	searchCompanies: SearchCompaniesResponse;
+};
+
+export const ZoominfoEndpointInputSchemas = {
+	searchCompanies: SearchCompaniesInputSchema,
+} as const;
+
+export const ZoominfoEndpointOutputSchemas = {
+	searchCompanies: SearchCompaniesResponseSchema,
+} as const;

packages/zoominfo/error-handlers.ts

@@ -0,0 +1,31 @@
+import type { CorsairErrorHandler } from 'corsair/core';
+import { ApiError } from 'corsair/http';
+
+export const errorHandlers = {
+	RATE_LIMIT_ERROR: {
+		match: (error: Error) => {
+			if (error instanceof ApiError && error.status === 429) return true;
+			const msg = error.message.toLowerCase();
+			return msg.includes('rate_limited') || msg.includes('429');
+		},
+		handler: async (error: Error) => {
+			let retryAfterMs: number | undefined;
+			if (error instanceof ApiError && error.retryAfter !== undefined) {
+				retryAfterMs = error.retryAfter;
+			}
+			return { maxRetries: 5, headersRetryAfterMs: retryAfterMs };
+		},
+	},
+	AUTH_ERROR: {
+		match: (error: Error) => {
+			if (error instanceof ApiError && error.status === 401) return true;
+			const msg = error.message.toLowerCase();
+			return msg.includes('unauthorized') || msg.includes('invalid_auth');
+		},
+		handler: async () => ({ maxRetries: 0 }),
+	},
+	DEFAULT: {
+		match: () => true,
+		handler: async () => ({ maxRetries: 0 }),
+	},
+} satisfies CorsairErrorHandler;

packages/zoominfo/index.ts

@@ -0,0 +1,210 @@
+import type {
+	AuthTypes,
+	BindEndpoints,
+	BindWebhooks,
+	CorsairEndpoint,
+	CorsairErrorHandler,
+	CorsairPlugin,
+	CorsairPluginContext,
+	CorsairWebhook,
+	KeyBuilderContext,
+	PickAuth,
+	PluginAuthConfig,
+	PluginPermissionsConfig,
+	RequiredPluginEndpointMeta,
+	RequiredPluginEndpointSchemas,
+	RequiredPluginWebhookSchemas,
+} from 'corsair/core';
+import { Zoominfo } from './endpoints';
+import type {
+	ZoominfoEndpointInputs,
+	ZoominfoEndpointOutputs,
+} from './endpoints/types';
+import {
+	ZoominfoEndpointInputSchemas,
+	ZoominfoEndpointOutputSchemas,
+} from './endpoints/types';
+import { errorHandlers } from './error-handlers';
+import { ZoominfoSchema } from './schema';
+import { ExampleWebhooks } from './webhooks';
+import { resolveZoominfoOAuthWebhookTenantLink } from './webhooks/oauth-tenant-link';
+import { matchZoominfoTenantWebhook } from './webhooks/tenant-matcher';
+import type { ExampleEvent, ZoominfoWebhookOutputs } from './webhooks/types';
+import { ExampleEventSchema } from './webhooks/types';
+
+export type ZoominfoPluginOptions = {
+	authType?: PickAuth<'api_key' | 'oauth_2'>;
+	key?: string;
+	webhookSecret?: string;
+	hooks?: InternalZoominfoPlugin['hooks'];
+	webhookHooks?: InternalZoominfoPlugin['webhookHooks'];
+	errorHandlers?: CorsairErrorHandler;
+	permissions?: PluginPermissionsConfig<typeof zoominfoEndpointsNested>;
+};
+
+export type ZoominfoContext = CorsairPluginContext<
+	typeof ZoominfoSchema,
+	ZoominfoPluginOptions
+>;
+
+export type ZoominfoKeyBuilderContext =
+	KeyBuilderContext<ZoominfoPluginOptions>;
+
+export type ZoominfoBoundEndpoints = BindEndpoints<
+	typeof zoominfoEndpointsNested
+>;
+
+type ZoominfoEndpoint<K extends keyof ZoominfoEndpointOutputs> =
+	CorsairEndpoint<
+		ZoominfoContext,
+		ZoominfoEndpointInputs[K],
+		ZoominfoEndpointOutputs[K]
+	>;
+
+export type ZoominfoEndpoints = {
+	exampleGet: ZoominfoEndpoint<'searchCompanies'>;
+};
+
+type ZoominfoWebhook<
+	K extends keyof ZoominfoWebhookOutputs,
+	TEvent,
+> = CorsairWebhook<ZoominfoContext, TEvent, ZoominfoWebhookOutputs[K]>;
+
+export type ZoominfoWebhooks = {
+	example: ZoominfoWebhook<'example', ExampleEvent>;
+};
+
+export type ZoominfoBoundWebhooks = BindWebhooks<ZoominfoWebhooks>;
+
+const zoominfoEndpointsNested = {
+	zoominfo: {
+		searchCompanies: Zoominfo.searchCompanies,
+	},
+} as const;
+
+const zoominfoWebhooksNested = {
+	zoominfo: {
+		searchCompanies: Zoominfo.searchCompanies,
+	},
+} as const;
+
+export const zoominfoEndpointSchemas = {
+	'zoominfo.searchCompanies': {
+		input: ZoominfoEndpointInputSchemas.searchCompanies,
+		output: ZoominfoEndpointOutputSchemas.searchCompanies,
+	},
+} as const satisfies RequiredPluginEndpointSchemas<
+	typeof zoominfoEndpointsNested
+>;
+
+const zoominfoWebhookSchemas = {
+	'example.example': {
+		description: 'An example webhook event',
+		payload: ExampleEventSchema,
+		response: ExampleEventSchema,
+	},
+} as const satisfies RequiredPluginWebhookSchemas<
+	typeof zoominfoWebhooksNested
+>;
+
+const defaultAuthType: AuthTypes = 'api_key' as const;
+
+const zoominfoEndpointMeta = {
+	'zoominfo.searchCompanies': {
+		riskLevel: 'read',
+		description: 'Search for companies in ZoomInfo',
+	},
+} as const satisfies RequiredPluginEndpointMeta<typeof zoominfoEndpointsNested>;
+
+export const zoominfoAuthConfig = {
+	api_key: {
+		account: ['tenant_external_id'] as const,
+	},
+	oauth_2: {
+		account: ['tenant_external_id'] as const,
+	},
+} as const satisfies PluginAuthConfig;
+
+export type BaseZoominfoPlugin<T extends ZoominfoPluginOptions> = CorsairPlugin<
+	'zoominfo',
+	typeof ZoominfoSchema,
+	typeof zoominfoEndpointsNested,
+	typeof zoominfoWebhooksNested,
+	T,
+	typeof defaultAuthType
+>;
+
+export type InternalZoominfoPlugin = BaseZoominfoPlugin<ZoominfoPluginOptions>;
+
+export type ExternalZoominfoPlugin<T extends ZoominfoPluginOptions> =
+	BaseZoominfoPlugin<T>;
+
+export function zoominfo<const T extends ZoominfoPluginOptions>(
+	incomingOptions: ZoominfoPluginOptions & T = {} as ZoominfoPluginOptions & T,
+): ExternalZoominfoPlugin<T> {
+	const options = {
+		...incomingOptions,
+		authType: incomingOptions.authType ?? defaultAuthType,
+	};
+	return {
+		id: 'zoominfo',
+		authConfig: zoominfoAuthConfig,
+		schema: ZoominfoSchema,
+		options: options,
+		hooks: options.hooks,
+		webhookHooks: options.webhookHooks,
+		endpoints: zoominfoEndpointsNested,
+		webhooks: zoominfoWebhooksNested,
+		endpointMeta: zoominfoEndpointMeta,
+		endpointSchemas: zoominfoEndpointSchemas,
+		webhookSchemas: zoominfoWebhookSchemas,
+		pluginWebhookMatcher: (request) => {
+			const headers = request.headers;
+			// TODO: Update to match your webhook signature headers
+			return 'x-zoominfo-signature' in headers;
+		},
+		pluginTenantWebhookMatcher: matchZoominfoTenantWebhook,
+		oauthWebhookTenantLinkResolver: resolveZoominfoOAuthWebhookTenantLink,
+		errorHandlers: {
+			...errorHandlers,
+			...options.errorHandlers,
+		},
+		keyBuilder: async (ctx: ZoominfoKeyBuilderContext, source) => {
+			if (source === 'webhook' && options.webhookSecret) {
+				return options.webhookSecret;
+			}
+
+			if (source === 'webhook') {
+				const res = await ctx.keys.get_webhook_signature();
+				return res ?? '';
+			}
+
+			if (source === 'endpoint' && options.key) {
+				return options.key;
+			}
+
+			if (source === 'endpoint' && ctx.authType === 'api_key') {
+				const res = await ctx.keys.get_api_key();
+				return res ?? '';
+			}
+
+			if (source === 'endpoint' && ctx.authType === 'oauth_2') {
+				const res = await ctx.keys.get_access_token();
+				return res ?? '';
+			}
+
+			return '';
+		},
+	} satisfies InternalZoominfoPlugin;
+}
+
+export type {
+	SearchCompaniesInput,
+	SearchCompaniesResponse,
+	ZoominfoEndpointInputs,
+	ZoominfoEndpointOutputs,
+} from './endpoints/types';
+export type {
+	ExampleEvent,
+	ZoominfoWebhookOutputs,
+} from './webhooks/types';