Validate Connector

Validate Connector Skill

Identify the runtime under review

For Sim Search, validate the live provider registration and access pipeline: catalog and metadata parity, both search/read handlers, current member grants, service-source restrictions, safe scoped references, pagination, provenance, and provider failure behavior. Test real localhost setup/search/read with authorized fixtures when available, and distinguish those results from mocked provider tests. Live Search must not enqueue content indexing or background ACL/directory builds; GitLab still computes request-time permissions or uses current CSV grants.

The ingestion-specific checks below apply to ordinary workspace KB connectors only. Do not require a live-only provider to implement content hashes, ingestion cursors, embeddings, or stored ACL snapshots.

You are an expert auditor for Sim knowledge base connectors. Your job is to thoroughly validate that an existing connector is correct, complete, and follows all conventions.

Your Task

When the user asks you to validate a connector:

1. Read the service's API documentation (via Context7 or WebFetch)
2. Read the connector implementation, OAuth config, and registry entries
3. Cross-reference everything against the API docs and Sim conventions
4. Report all issues found, grouped by severity (critical, warning, suggestion)
5. Fix all issues after reporting them

Step 1: Gather All Files

Read every file for the connector — do not skip any:

apps/sim/connectors/{service}/meta.ts        # ConnectorMeta — client-safe metadata (icon, name, auth, configFields, tagDefinitions)
apps/sim/connectors/{service}/{service}.ts   # Connector implementation — spreads the meta + runtime functions
apps/sim/connectors/{service}/index.ts       # Barrel export
apps/sim/connectors/registry.server.ts       # Server-only full registry entry (CONNECTOR_REGISTRY; full connector)
apps/sim/connectors/registry.ts              # Client-safe meta registry entry (CONNECTOR_META_REGISTRY)
apps/sim/connectors/types.ts                 # ConnectorMeta / ConnectorConfig interfaces, ExternalDocument, etc.
apps/sim/connectors/utils.ts                 # Shared utilities (computeContentHash, htmlToPlainText, etc.)
apps/sim/lib/oauth/oauth.ts                  # OAUTH_PROVIDERS — single source of truth for scopes
apps/sim/lib/oauth/utils.ts                  # getCanonicalScopesForProvider, getScopesForService, SCOPE_DESCRIPTIONS
apps/sim/lib/oauth/types.ts                  # OAuthService union type
apps/sim/components/icons.tsx                 # Icon definition for the service

If the connector uses selectors, also read:

apps/sim/lib/selectors/manifest.ts            # Browser-safe exhaustive metadata
apps/sim/lib/selectors/types.ts               # Selector context and option types
apps/sim/lib/selectors/context.ts             # Active canonical context projection
apps/sim/lib/selectors/server/registry.ts     # Exhaustive server attachments
apps/sim/lib/selectors/server/providers/*     # Matching provider attachment

Apply the validate-selector skill to the matching key and provider primitive. There is no client provider selector registry.

Step 2: Pull API Documentation

Fetch the official API docs for the service. This is the source of truth for:

• Endpoint URLs, HTTP methods, and auth headers
• Required vs optional parameters
• Parameter types and allowed values
• Response shapes and field names
• Pagination patterns (cursor, offset, next token)
• Rate limits and error formats
• OAuth scopes and their meanings

Use Context7 (resolve-library-id → query-docs) or WebFetch to retrieve documentation. If both fail, note which claims are based on training knowledge vs verified docs.

Hard Rule: No Guessed Source Schemas

If the service docs do not clearly show document list responses, document fetch responses, metadata fields, or pagination shapes, you MUST tell the user instead of guessing.

• Do NOT infer document fields from unrelated endpoints
• Do NOT guess pagination cursors or response wrappers
• Do NOT assume metadata keys that are not documented
• Do NOT treat probable shapes as validated

If a schema is unknown, validation must explicitly recommend:

1. sample API responses,
2. live test credentials, or
3. trimming the connector to only documented fields.

Step 3: Validate API Endpoints

For every API call in the connector (listDocuments, getDocument, validateConfig, and any helper functions), verify against the API docs:

URLs and Methods

• Base URL is correct for the service's API version
• Endpoint paths match the API docs exactly
• HTTP method is correct (GET, POST, PUT, PATCH, DELETE)
• Path parameters are correctly interpolated and URI-encoded where needed
• Query parameters use correct names and formats per the API docs

Headers

• Authorization header uses the correct format:
  • OAuth: Authorization: Bearer ${accessToken}
  • API Key: correct header name per the service's docs
• Content-Type is set for POST/PUT/PATCH requests
• Any service-specific headers are present (e.g., Notion-Version, Dropbox-API-Arg)
• No headers are sent that the API doesn't support or silently ignores

Request Bodies

• POST/PUT body fields match API parameter names exactly
• Required fields are always sent
• Optional fields are conditionally included (not sent as null or empty unless the API expects that)
• Field value types match API expectations (string vs number vs boolean)

Input Sanitization

• User-controlled values interpolated into query strings are properly escaped:
  • OData $filter: single quotes escaped with '' (e.g., externalId.replace(/'/g, "''"))
  • SOQL: single quotes escaped with \'
  • GraphQL variables: passed as variables, not interpolated into query strings
  • URL path segments: encodeURIComponent() applied
• URL-type config fields (e.g., siteUrl, instanceUrl) are normalized:
  • Strip https:// / http:// prefix if the API expects bare domains
  • Strip trailing /
  • Apply .trim() before validation

Response Parsing

• Response structure is correctly traversed (e.g., data.results vs data.items vs data)
• Field names extracted match what the API actually returns
• Nullable fields are handled with ?? null or || undefined
• Error responses are checked before accessing data fields
• Every extracted field and pagination value is backed by official docs or live-verified sample payloads

Step 4: Validate OAuth Scopes (if OAuth connector)

Scopes must be correctly declared and sufficient for all API calls the connector makes.

Connector requiredScopes

• requiredScopes in the connector's auth config lists all scopes needed by the connector
• Each scope in requiredScopes is a real, valid scope recognized by the service's API
• No invalid, deprecated, or made-up scopes are listed
• No unnecessary excess scopes beyond what the connector actually needs

Scope Subset Validation (CRITICAL)

• Every scope in requiredScopes exists in the OAuth provider's scopes array in lib/oauth/oauth.ts
• Find the provider in OAUTH_PROVIDERS[providerGroup].services[serviceId].scopes
• Verify: requiredScopes ⊆ OAUTH_PROVIDERS scopes (every required scope is present in the provider config)
• If a required scope is NOT in the provider config, flag as critical — the connector will fail at runtime

Scope Sufficiency

For each API endpoint the connector calls:

• Identify which scopes are required per the API docs
• Verify those scopes are included in the connector's requiredScopes
• If the connector calls endpoints requiring scopes not in requiredScopes, flag as warning

Token Refresh Config

• Check the provider's entry in getProviderAuthConfig (lib/oauth/oauth.ts)
• useBasicAuth matches the service's token exchange requirements
• supportsRefreshTokenRotation matches whether the service issues rotating refresh tokens
• Token endpoint URL is correct

Step 5: Validate Pagination

listDocuments Pagination

• Cursor/pagination parameter name matches the API docs
• Response pagination field is correctly extracted (e.g., next_cursor, nextPageToken, @odata.nextLink, offset)
• hasMore is correctly determined from the response
• nextCursor is correctly passed back for the next page
• maxItems / maxRecords cap is correctly applied across pages using syncContext.totalDocsFetched
• Page size is within the API's allowed range (not exceeding max page size)
• Last page precision: when a maxItems cap exists, the final page request uses Math.min(PAGE_SIZE, remaining) to avoid fetching more records than needed
• No off-by-one errors in pagination tracking
• The connector does NOT hit known API pagination limits silently (e.g., HubSpot search 10k cap)

Deletion-Reconciliation Safety (listingCapped) — CRITICAL

The sync engine tombstones, then hard-deletes, any stored document absent from a full listing. Audit every path where listDocuments can return less than the full source set:

• syncContext.listingCapped = true is set when a maxItems-style cap truncates the listing while more documents exist
• listingCapped is set when a transient per-item error drops a still-existing document from the listing
• listingCapped is NOT set when the source is genuinely exhausted (deleted documents must reconcile) or for intentional scope filters (date cutoffs) Verify it against the checkpoint.unsafe computation in lib/knowledge/connectors/listing-checkpoint.ts.

Pagination State Across Pages

• syncContext is used to cache state across pages (user names, field maps, instance URLs, portal IDs, etc.)
• Cached state in syncContext is correctly initialized on first page and reused on subsequent pages

Step 6: Validate Data Transformation

Content Deferral (CRITICAL)

Connectors that require per-document API calls to fetch content (file download, export, blocks fetch) MUST use contentDeferred: true. This is the standard pattern for reliability — without it, content downloads during listing can exhaust the sync task's time budget before any documents are saved.

• If the connector downloads content per-doc during listDocuments, it MUST use contentDeferred: true instead
• listDocuments returns lightweight stubs with content: '' and contentDeferred: true
• getDocument fetches actual content and returns the full document with contentDeferred: false
• A shared stub function (e.g., fileToStub) is used by both listDocuments and getDocument to guarantee contentHash consistency
• contentHash is metadata-based (e.g., service:{id}:{modifiedTime}), NOT content-based — it must be derivable from list metadata alone
• The contentHash is identical whether produced by listDocuments or getDocument

Connectors where the list API already returns content inline (e.g., Slack messages, Reddit posts) do NOT need contentDeferred.

ExternalDocument Construction

• externalId is a stable, unique identifier from the source API
• title is extracted from the correct field and has a sensible fallback (e.g., 'Untitled')
• content is plain text — HTML content is stripped using htmlToPlainText from @/connectors/utils
• mimeType is 'text/plain' for extracted text, or the document hands over sourceFile for a format the KB pipeline parses
• contentHash uses a metadata-based format (e.g., service:{id}:{modifiedTime}) for connectors with contentDeferred: true, or computeContentHash from @/connectors/utils for inline-content connectors
• sourceUrl is a valid, complete URL back to the original resource (not relative)
• metadata contains all fields referenced by mapTags and tagDefinitions

Content Extraction

• Rich text / HTML fields are converted to plain text before indexing
• Important content is not silently dropped (e.g., nested blocks, table cells, code blocks)
• Content is not silently truncated without logging a warning
• Empty/blank documents are properly filtered out
• Size checks use Buffer.byteLength(text, 'utf8') not text.length when comparing against byte-based limits (e.g., MAX_FILE_SIZE in bytes)

Step 7: Validate Tag Definitions and mapTags

tagDefinitions

• Each tagDefinition has an id, displayName, and fieldType
• fieldType matches the actual data type: 'text' for strings, 'number' for numbers, 'date' for dates, 'boolean' for booleans
• Every id in tagDefinitions is returned by mapTags
• No tagDefinition references a field that mapTags never produces

mapTags

• Return keys match tagDefinition id values exactly
• Date values are properly parsed using parseTagDate from @/connectors/utils
• Array values are properly joined using joinTagArray from @/connectors/utils
• Number values are validated (not NaN)
• Metadata field names accessed in mapTags match what listDocuments/getDocument store in metadata

Step 8: Validate Config Fields and Validation

configFields

• Every field has id, title, type
• required is set explicitly (not omitted)
• Dropdown fields have options with label and id for each option
• Selector fields follow the canonical pair pattern:
  • A type: 'selector' field with selectorKey, canonicalParamId, mode: 'basic'
  • A type: 'short-input' field with the same canonicalParamId, mode: 'advanced'
  • required is identical on both fields in the pair
• dependsOn references selector field id values, not canonicalParamId
• Each selector key passes the validate-selector skill