feat: add Agility CMS plugin

packages/agilitycms/client.ts

@@ -0,0 +1,64 @@
+import type { ApiRequestOptions, OpenAPIConfig } from 'corsair/http';
+import { request } from 'corsair/http';
+
+export class AgilityCmsAPIError extends Error {
+	constructor(
+		message: string,
+		public readonly code?: string,
+	) {
+		super(message);
+		this.name = 'AgilityCmsAPIError';
+	}
+}
+
+const AGILITYCMS_API_BASE = 'https://api.aglty.io';
+
+export async function makeAgilityCmsRequest<T>(
+	instanceGuid: string,
+	apiKey: string,
+	apiType: 'fetch' | 'preview',
+	endpoint: string,
+	options: {
+		method?: 'GET';
+		query?: Record<string, string | number | boolean | undefined>;
+	} = {},
+): Promise<T> {
+	const { method = 'GET', query } = options;
+
+	if (!instanceGuid) {
+		throw new AgilityCmsAPIError('Agility CMS instance GUID is required');
+	}
+
+	if (!apiKey) {
+		throw new AgilityCmsAPIError('Agility CMS API key is required');
+	}
+
+	const config: OpenAPIConfig = {
+		BASE: `${AGILITYCMS_API_BASE}/${instanceGuid}/${apiType}`,
+		VERSION: '1.0.0',
+		WITH_CREDENTIALS: false,
+		CREDENTIALS: 'omit',
+		TOKEN: undefined,
+		HEADERS: {
+			Accept: 'application/json',
+			APIKey: apiKey,
+		},
+	};
+
+	const requestOptions: ApiRequestOptions = {
+		method,
+		url: endpoint,
+		mediaType: 'application/json',
+		query,
+	};
+
+	try {
+		return await request<T>(config, requestOptions);
+	} catch (error) {
+		if (error instanceof Error) {
+			throw new AgilityCmsAPIError(error.message);
+		}
+
+		throw new AgilityCmsAPIError('Unknown Agility CMS API error');
+	}
+}

packages/agilitycms/endpoints/example.ts

@@ -0,0 +1,115 @@
+import { logEventFromContext } from 'corsair/core';
+import type { AgilityCmsEndpoints } from '..';
+import { makeAgilityCmsRequest } from '../client';
+import type { AgilityCmsEndpointOutputs } from './types';
+
+export const getPage: AgilityCmsEndpoints['getPage'] = async (ctx, input) => {
+	const response = await makeAgilityCmsRequest<
+		AgilityCmsEndpointOutputs['getPage']
+	>(
+		input.instanceGuid,
+		ctx.key,
+		input.apiType,
+		`${input.locale}/page/${input.pageId}`,
+	);
+
+	await logEventFromContext(
+		ctx,
+		'agilitycms.content.getPage',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};
+
+export const getItem: AgilityCmsEndpoints['getItem'] = async (ctx, input) => {
+	const response = await makeAgilityCmsRequest<
+		AgilityCmsEndpointOutputs['getItem']
+	>(
+		input.instanceGuid,
+		ctx.key,
+		input.apiType,
+		`${input.locale}/item/${input.contentId}`,
+	);
+
+	await logEventFromContext(
+		ctx,
+		'agilitycms.content.getItem',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};
+
+export const getList: AgilityCmsEndpoints['getList'] = async (ctx, input) => {
+	const response = await makeAgilityCmsRequest<
+		AgilityCmsEndpointOutputs['getList']
+	>(
+		input.instanceGuid,
+		ctx.key,
+		input.apiType,
+		`${input.locale}/list/${input.referenceName}`,
+		{
+			query: {
+				contentLinkDepth: input.contentLinkDepth,
+				expandAllContentLinks: input.expandAllContentLinks,
+				take: input.take,
+				skip: input.skip,
+				sort: input.sort,
+				filter: input.filter,
+			},
+		},
+	);
+
+	await logEventFromContext(
+		ctx,
+		'agilitycms.content.getList',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};
+
+export const getSitemap: AgilityCmsEndpoints['getSitemap'] = async (
+	ctx,
+	input,
+) => {
+	const response = await makeAgilityCmsRequest<
+		AgilityCmsEndpointOutputs['getSitemap']
+	>(
+		input.instanceGuid,
+		ctx.key,
+		input.apiType,
+		`${input.locale}/sitemap/flat/${input.channelName}`,
+	);
+
+	await logEventFromContext(
+		ctx,
+		'agilitycms.content.getSitemap',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};
+
+export const getContentModels: AgilityCmsEndpoints['getContentModels'] = async (
+	ctx,
+	input,
+) => {
+	const response = await makeAgilityCmsRequest<
+		AgilityCmsEndpointOutputs['getContentModels']
+	>(input.instanceGuid, ctx.key, input.apiType, `${input.locale}/models`);
+
+	await logEventFromContext(
+		ctx,
+		'agilitycms.content.getContentModels',
+		{ ...input },
+		'completed',
+	);
+
+	return response;
+};

packages/agilitycms/endpoints/index.ts

@@ -0,0 +1,17 @@
+import {
+	getContentModels,
+	getItem,
+	getList,
+	getPage,
+	getSitemap,
+} from './example';
+
+export const Content = {
+	getPage,
+	getItem,
+	getList,
+	getSitemap,
+	getContentModels,
+};
+
+export * from './types';

packages/agilitycms/endpoints/types.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+
+const GetPageInputSchema = z.object({
+	instanceGuid: z.string().min(1),
+	locale: z.string().min(1),
+	pageId: z.number().int().positive(),
+	apiType: z.enum(['fetch', 'preview']).default('fetch'),
+});
+
+const GetItemInputSchema = z.object({
+	instanceGuid: z.string().min(1),
+	locale: z.string().min(1),
+	contentId: z.number().int().positive(),
+	apiType: z.enum(['fetch', 'preview']).default('fetch'),
+});
+
+const GetListInputSchema = z.object({
+	instanceGuid: z.string().min(1),
+	locale: z.string().min(1),
+	referenceName: z.string().min(1),
+	apiType: z.enum(['fetch', 'preview']).default('fetch'),
+	contentLinkDepth: z.number().int().min(0).optional(),
+	expandAllContentLinks: z.boolean().optional(),
+	take: z.number().int().positive().optional(),
+	skip: z.number().int().min(0).optional(),
+	sort: z.string().optional(),
+	filter: z.string().optional(),
+});
+
+const GetSitemapInputSchema = z.object({
+	instanceGuid: z.string().min(1),
+	locale: z.string().min(1),
+	channelName: z.string().min(1),
+	apiType: z.enum(['fetch', 'preview']).default('fetch'),
+});
+
+const GetContentModelsInputSchema = z.object({
+	instanceGuid: z.string().min(1),
+	locale: z.string().min(1),
+	apiType: z.enum(['fetch', 'preview']).default('fetch'),
+});
+
+export type GetPageInput = z.infer<typeof GetPageInputSchema>;
+export type GetItemInput = z.infer<typeof GetItemInputSchema>;
+export type GetListInput = z.infer<typeof GetListInputSchema>;
+export type GetSitemapInput = z.infer<typeof GetSitemapInputSchema>;
+export type GetContentModelsInput = z.infer<typeof GetContentModelsInputSchema>;
+
+export type AgilityCmsEndpointInputs = {
+	getPage: GetPageInput;
+	getItem: GetItemInput;
+	getList: GetListInput;
+	getSitemap: GetSitemapInput;
+	getContentModels: GetContentModelsInput;
+};
+
+export type AgilityCmsEndpointOutputs = {
+	getPage: Record<string, unknown>;
+	getItem: Record<string, unknown>;
+	getList: Record<string, unknown>;
+	getSitemap: Record<string, unknown>;
+	getContentModels: Record<string, unknown>;
+};
+
+export const AgilityCmsEndpointInputSchemas = {
+	getPage: GetPageInputSchema,
+	getItem: GetItemInputSchema,
+	getList: GetListInputSchema,
+	getSitemap: GetSitemapInputSchema,
+	getContentModels: GetContentModelsInputSchema,
+} as const;
+
+export const AgilityCmsEndpointOutputSchemas = {
+	getPage: z.record(z.string(), z.unknown()),
+	getItem: z.record(z.string(), z.unknown()),
+	getList: z.record(z.string(), z.unknown()),
+	getSitemap: z.record(z.string(), z.unknown()),
+	getContentModels: z.record(z.string(), z.unknown()),
+} as const;

packages/agilitycms/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;