REPOSITORY: corsairdev/corsair PR: #878

Integration Specification: Google SERP Plugin Package

Engineering implementation report documenting the structure, contracts, validation models, and error behaviors for the new @corsair-dev/autom plugin package.

Merged Integration approved and deployed into main branch repository vocabulary.

1. Overview & Objectives

This report documents the architectural design and code structure of the Autom.dev search plugin integration. The integration enables AI agents utilizing the Corsair framework to execute Google search queries and target localize regional data seamlessly.

The implementation focuses on four main engineering parameters:

Unified Registration: Aligning Autom.dev with Corsair’s standard provider-plugin architecture.
Type-Safety Boundaries: Validating both request variables and API responses using Zod schemas.
Robust Exception Handling: Preventing data loss by propagating transport-level errors safely to the framework retry policy.
Testing Integrity: Validating schema properties and API operation logic with complete test suites.

2. Implemented API Operations

The package implements four endpoints registered under the google tool schema:

Endpoint Name	HTTP Method	API Resource Path	Functional Purpose
`google.images`	GET	`/v1/google/images`	Google Images SERP queries (supporting size filters, pagination, and source domains).
`google.countries`	GET	`/v1/finder/google-countries`	Finds supported country search regions matching a query.
`google.languages`	GET	`/v1/finder/google-languages`	Finds localization language codes supported by Google.
`google.locations`	GET	`/v1/finder/google-locations`	Queries geographic target locations ordered by user reach.

3. Data Schema & Type Validation

To enforce strict type safety and protect the LLM context from corrupted data formats, input parameters and response objects are validated using Zod models before leaving the plugin bounds.

For example, the search inputs are schema-checked as follows:

// Example schema validation code
export const GoogleImagesInput = z.object({
    query: z.string().min(1, 'Search query cannot be empty'),
    page: z.number().int().positive().default(1),
    country: z.string().optional(),
    language: z.string().optional(),
    safeSearch: z.boolean().optional(),
});

4. Error Handling & Retry Protocol

To ensure robust error handling, the client has been designed to rethrow standard ApiError instances directly rather than hiding them under generic wrappers.

This retains critical status metadata, such as:

HTTP 429 Status Codes (Rate Limits)
Retry-After Headers (Provided by the server)

This allows Corsair's framework-level error handlers to correctly intercept rate limits and delay further execution appropriately:

// client.ts error propagation flow
try {
    return await request<T>(config, requestOptions);
} catch (error) {
    if (error instanceof ApiError) throw error; // Preserved for retry logic
    if (error instanceof Error) throw new AutomAPIError(error.message);
    throw new AutomAPIError('Unknown error');
}

5. Verification & Quality Assurance

The code is fully verified locally and passing CI gates. The test suite contains 18 unit tests grouped across four test suites:

schema.test.ts: Asserts schema structures compatibility and semver compliance.
operations.test.ts: Validates endpoint parameters mapping, query handling, and payload schemas.
client.test.ts: Verifies API key validations and correct client initialization parameters.
error-handlers.test.ts: Checks rate-limit status classifications and retries limits mappings.

"Validation, retry policy, and auth handling look correct. Fine to merge, thanks!"
— PR Review approval comment by maintainer Ambikesh