Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
48.8 KB
Raw Blame
import type { z } from "zod"
import {
  accessGrantListResponseSchema,
  accessGrantMutationResponseSchema,
  configObjectAccessGrantParamsSchema,
  configObjectCreateSchema,
  configObjectCreateVersionSchema,
  configObjectDetailResponseSchema,
  configObjectListQuerySchema,
  configObjectListResponseSchema,
  configObjectMutationResponseSchema,
  configObjectParamsSchema,
  configObjectPluginAttachSchema,
  configObjectVersionDetailResponseSchema,
  configObjectVersionListQuerySchema,
  configObjectVersionListResponseSchema,
  configObjectVersionParamsSchema,
  connectorAccountCreateSchema,
  connectorAccountDetailResponseSchema,
  connectorAccountDisconnectSchema,
  connectorAccountListQuerySchema,
  connectorAccountListResponseSchema,
  connectorAccountDisconnectResponseSchema,
  connectorAccountMutationResponseSchema,
  connectorInstanceAutoImportSchema,
  connectorInstanceConfigurationResponseSchema,
  connectorInstanceRemoveResponseSchema,
  connectorAccountParamsSchema,
  connectorAccountRepositoryParamsSchema,
  connectorInstanceAccessGrantParamsSchema,
  connectorInstanceCreateSchema,
  connectorInstanceDetailResponseSchema,
  connectorInstanceListQuerySchema,
  connectorInstanceListResponseSchema,
  connectorInstanceMutationResponseSchema,
  connectorInstanceSyncNowResponseSchema,
  connectorInstanceParamsSchema,
  connectorInstanceUpdateSchema,
  connectorMappingCreateSchema,
  connectorMappingListQuerySchema,
  connectorMappingListResponseSchema,
  connectorMappingMutationResponseSchema,
  connectorMappingParamsSchema,
  connectorMappingUpdateSchema,
  connectorSyncAsyncResponseSchema,
  connectorSyncEventDetailResponseSchema,
  connectorSyncEventListQuerySchema,
  connectorSyncEventListResponseSchema,
  connectorSyncEventParamsSchema,
  connectorTargetCreateSchema,
  connectorTargetDetailResponseSchema,
  connectorTargetListQuerySchema,
  connectorTargetListResponseSchema,
  connectorTargetMutationResponseSchema,
  connectorTargetParamsSchema,
  connectorTargetUpdateSchema,
  githubConnectorAccountCreateSchema,
  githubConnectorDiscoveryResponseSchema,
  githubDiscoveryApplyResponseSchema,
  githubDiscoveryApplySchema,
  githubDiscoveryTreeQuerySchema,
  githubDiscoveryTreeResponseSchema,
  githubInstallCompleteResponseSchema,
  githubInstallCompleteSchema,
  githubInstallStartResponseSchema,
  githubInstallStartSchema,
  githubConnectorSetupSchema,
  githubRepositoryListQuerySchema,
  githubRepositoryListResponseSchema,
  githubSetupResponseSchema,
  githubValidateTargetResponseSchema,
  githubValidateTargetSchema,
  githubWebhookAcceptedResponseSchema,
  githubWebhookHeadersSchema,
  githubWebhookIgnoredResponseSchema,
  githubWebhookRawBodySchema,
  githubWebhookUnauthorizedResponseSchema,
  marketplaceAccessGrantParamsSchema,
  marketplaceCreateSchema,
  marketplaceDetailResponseSchema,
  marketplaceListQuerySchema,
  marketplaceListResponseSchema,
  marketplaceMutationResponseSchema,
  marketplaceParamsSchema,
  marketplacePluginListResponseSchema,
  marketplaceResolvedResponseSchema,
  marketplacePluginMutationResponseSchema,
  marketplacePluginParamsSchema,
  marketplacePluginWriteSchema,
  marketplaceUpdateSchema,
  meLibraryListResponseSchema,
  mePluginAccessListResponseSchema,
  pluginAccessGrantParamsSchema,
  pluginConfigObjectParamsSchema,
  pluginCreateSchema,
  pluginDetailResponseSchema,
  pluginListQuerySchema,
  pluginListResponseSchema,
  pluginMcpRequirementConfigureResponseSchema,
  pluginMcpRequirementConfigureSchema,
  pluginMembershipMutationResponseSchema,
  pluginMembershipListResponseSchema,
  pluginMembershipWriteSchema,
  pluginMutationResponseSchema,
  pluginParamsSchema,
  pluginUpdateSchema,
  resourceAccessGrantWriteSchema,
  teamParamsSchema,
  teamPluginAccessListResponseSchema,
} from "./schemas.js"

type EndpointMethod = "DELETE" | "GET" | "PATCH" | "POST"
type EndpointAudience = "admin" | "member" | "public_webhook"
type EndpointTag = "Config Objects" | "Plugins" | "Marketplaces" | "Connectors" | "GitHub" | "Webhooks"

type EndpointContract = {
  audience: EndpointAudience
  description: string
  method: EndpointMethod
  path: string
  request?: {
    body?: z.ZodTypeAny
    headers?: z.ZodTypeAny
    params?: z.ZodTypeAny
    query?: z.ZodTypeAny
  }
  response: {
    description: string
    schema?: z.ZodTypeAny
    status: 200 | 201 | 202 | 204 | 401
  }
  tag: EndpointTag
}

type DeferredEndpointContract = {
  description: string
  method: EndpointMethod
  path: string
  reason: string
  tag: EndpointTag
}

const orgBasePath = "/v1"

export const pluginArchRoutePaths = {
  configObjects: `${orgBasePath}/config-objects`,
  configObject: `${orgBasePath}/config-objects/:configObjectId`,
  configObjectArchive: `${orgBasePath}/config-objects/:configObjectId/archive`,
  configObjectDelete: `${orgBasePath}/config-objects/:configObjectId/delete`,
  configObjectRestore: `${orgBasePath}/config-objects/:configObjectId/restore`,
  configObjectPlugins: `${orgBasePath}/config-objects/:configObjectId/plugins`,
  configObjectPlugin: `${orgBasePath}/config-objects/:configObjectId/plugins/:pluginId`,
  configObjectAccess: `${orgBasePath}/config-objects/:configObjectId/access`,
  configObjectAccessGrant: `${orgBasePath}/config-objects/:configObjectId/access/:grantId`,
  configObjectVersions: `${orgBasePath}/config-objects/:configObjectId/versions`,
  configObjectVersion: `${orgBasePath}/config-objects/:configObjectId/versions/:versionId`,
  configObjectLatestVersion: `${orgBasePath}/config-objects/:configObjectId/versions/latest`,
  configObjectCompareVersions: `${orgBasePath}/config-objects/:configObjectId/versions/compare`,
  skills: `${orgBasePath}/skills`,
  agents: `${orgBasePath}/agents`,
  commands: `${orgBasePath}/commands`,
  tools: `${orgBasePath}/tools`,
  mcps: `${orgBasePath}/mcps`,
  plugins: `${orgBasePath}/plugins`,
  plugin: `${orgBasePath}/plugins/:pluginId`,
  pluginArchive: `${orgBasePath}/plugins/:pluginId/archive`,
  pluginRestore: `${orgBasePath}/plugins/:pluginId/restore`,
  pluginConfigObjects: `${orgBasePath}/plugins/:pluginId/config-objects`,
  pluginConfigObject: `${orgBasePath}/plugins/:pluginId/config-objects/:configObjectId`,
  pluginMcpConnections: `${orgBasePath}/plugins/:pluginId/mcp-connections`,
  pluginResolved: `${orgBasePath}/plugins/:pluginId/resolved`,
  pluginReleases: `${orgBasePath}/plugins/:pluginId/releases`,
  pluginAccess: `${orgBasePath}/plugins/:pluginId/access`,
  pluginAccessGrant: `${orgBasePath}/plugins/:pluginId/access/:grantId`,
  meLibrary: `${orgBasePath}/me/library`,
  mePluginAccess: `${orgBasePath}/me/plugin-access`,
  teamPluginAccess: `${orgBasePath}/teams/:teamId/plugin-access`,
  pluginGithubMcpImportPreview: `${orgBasePath}/plugins/import-mcps-from-github-url/preview`,
  pluginGithubMcpImport: `${orgBasePath}/plugins/import-mcps-from-github-url`,
  marketplaces: `${orgBasePath}/marketplaces`,
  marketplace: `${orgBasePath}/marketplaces/:marketplaceId`,
  marketplaceResolved: `${orgBasePath}/marketplaces/:marketplaceId/resolved`,
  marketplaceArchive: `${orgBasePath}/marketplaces/:marketplaceId/archive`,
  marketplaceDelete: `${orgBasePath}/marketplaces/:marketplaceId/delete`,
  marketplaceRestore: `${orgBasePath}/marketplaces/:marketplaceId/restore`,
  marketplacePlugins: `${orgBasePath}/marketplaces/:marketplaceId/plugins`,
  marketplacePlugin: `${orgBasePath}/marketplaces/:marketplaceId/plugins/:pluginId`,
  marketplaceAccess: `${orgBasePath}/marketplaces/:marketplaceId/access`,
  marketplaceAccessGrant: `${orgBasePath}/marketplaces/:marketplaceId/access/:grantId`,
  connectorAccounts: `${orgBasePath}/connector-accounts`,
  connectorAccount: `${orgBasePath}/connector-accounts/:connectorAccountId`,
  connectorAccountDisconnect: `${orgBasePath}/connector-accounts/:connectorAccountId/disconnect`,
  connectorInstances: `${orgBasePath}/connector-instances`,
  connectorInstance: `${orgBasePath}/connector-instances/:connectorInstanceId`,
  connectorInstanceConfiguration: `${orgBasePath}/connector-instances/:connectorInstanceId/configuration`,
  connectorInstanceAutoImport: `${orgBasePath}/connector-instances/:connectorInstanceId/auto-import`,
  connectorInstanceRemove: `${orgBasePath}/connector-instances/:connectorInstanceId/remove`,
  connectorInstanceArchive: `${orgBasePath}/connector-instances/:connectorInstanceId/archive`,
  connectorInstanceDisable: `${orgBasePath}/connector-instances/:connectorInstanceId/disable`,
  connectorInstanceEnable: `${orgBasePath}/connector-instances/:connectorInstanceId/enable`,
  connectorInstanceSyncNow: `${orgBasePath}/connector-instances/:connectorInstanceId/sync-now`,
  connectorInstanceAccess: `${orgBasePath}/connector-instances/:connectorInstanceId/access`,
  connectorInstanceAccessGrant: `${orgBasePath}/connector-instances/:connectorInstanceId/access/:grantId`,
  connectorTargets: `${orgBasePath}/connector-instances/:connectorInstanceId/targets`,
  connectorTarget: `${orgBasePath}/connector-targets/:connectorTargetId`,
  connectorTargetResync: `${orgBasePath}/connector-targets/:connectorTargetId/resync`,
  connectorTargetMappings: `${orgBasePath}/connector-targets/:connectorTargetId/mappings`,
  connectorMapping: `${orgBasePath}/connector-mappings/:connectorMappingId`,
  connectorMappingPreview: `${orgBasePath}/connector-mappings/:connectorMappingId/preview`,
  connectorSyncEvents: `${orgBasePath}/connector-sync-events`,
  connectorSyncEvent: `${orgBasePath}/connector-sync-events/:connectorSyncEventId`,
  connectorSyncEventRetry: `${orgBasePath}/connector-sync-events/:connectorSyncEventId/retry`,
  connectorInstanceDiscovery: `${orgBasePath}/connector-instances/:connectorInstanceId/discovery`,
  connectorInstanceDiscoveryApply: `${orgBasePath}/connector-instances/:connectorInstanceId/discovery/apply`,
  connectorInstanceDiscoveryTree: `${orgBasePath}/connector-instances/:connectorInstanceId/discovery/tree`,
  githubInstallStart: `${orgBasePath}/connectors/github/install/start`,
  githubInstallComplete: `${orgBasePath}/connectors/github/install/complete`,
  githubSetup: `${orgBasePath}/connectors/github/setup`,
  githubAccounts: `${orgBasePath}/connectors/github/accounts`,
  githubAccountRepositories: `${orgBasePath}/connectors/github/accounts/:connectorAccountId/repositories`,
  githubValidateTarget: `${orgBasePath}/connectors/github/validate-target`,
  githubWebhookIngress: "/v1/webhooks/connectors/github",
} as const

export const pluginArchEndpointContracts: Record<string, EndpointContract> = {
  listConfigObjects: {
    audience: "admin",
    description: "List current config object projections with search and connector filters.",
    method: "GET",
    path: pluginArchRoutePaths.configObjects,
    request: { query: configObjectListQuerySchema },
    response: { description: "Current config object rows.", schema: configObjectListResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  getConfigObject: {
    audience: "admin",
    description: "Get one config object with its latest version projection.",
    method: "GET",
    path: pluginArchRoutePaths.configObject,
    request: { params: configObjectParamsSchema },
    response: { description: "Current config object detail.", schema: configObjectDetailResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  createConfigObject: {
    audience: "member",
    description: "Create a cloud or imported config object and optionally attach it to plugins.",
    method: "POST",
    path: pluginArchRoutePaths.configObjects,
    request: { body: configObjectCreateSchema },
    response: { description: "Config object created successfully.", schema: configObjectMutationResponseSchema, status: 201 },
    tag: "Config Objects",
  },
  createConfigObjectVersion: {
    audience: "admin",
    description: "Update an existing config object, including a Cloud skill, by creating a new immutable version without creating a duplicate.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectVersions,
    request: { body: configObjectCreateVersionSchema, params: configObjectParamsSchema },
    response: { description: "Latest config object detail after version creation.", schema: configObjectMutationResponseSchema, status: 201 },
    tag: "Config Objects",
  },
  archiveConfigObject: {
    audience: "admin",
    description: "Archive a config object without removing history.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectArchive,
    request: { params: configObjectParamsSchema },
    response: { description: "Archived config object detail.", schema: configObjectMutationResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  deleteConfigObject: {
    audience: "admin",
    description: "Soft-delete a config object while preserving history.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectDelete,
    request: { params: configObjectParamsSchema },
    response: { description: "Deleted config object detail.", schema: configObjectMutationResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  restoreConfigObject: {
    audience: "admin",
    description: "Restore a deleted or archived config object.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectRestore,
    request: { params: configObjectParamsSchema },
    response: { description: "Restored config object detail.", schema: configObjectMutationResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  listConfigObjectPlugins: {
    audience: "admin",
    description: "List the plugins that currently include a config object.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectPlugins,
    request: { params: configObjectParamsSchema },
    response: { description: "Plugin memberships for the config object.", schema: pluginMembershipListResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  attachConfigObjectToPlugin: {
    audience: "admin",
    description: "Attach a config object to a plugin using plugin-scoped write access. Attaching a Workflow additionally requires manager access to that Workflow because Plugin or Marketplace membership can expand its audience.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectPlugins,
    request: { body: configObjectPluginAttachSchema, params: configObjectParamsSchema },
    response: { description: "Plugin membership created successfully.", schema: pluginMembershipMutationResponseSchema, status: 201 },
    tag: "Config Objects",
  },
  removeConfigObjectFromPlugin: {
    audience: "admin",
    description: "Remove one active plugin membership from a config object. Removing a Workflow additionally requires manager access to that Workflow because it revokes inherited Plugin or Marketplace access.",
    method: "DELETE",
    path: pluginArchRoutePaths.configObjectPlugin,
    request: { params: configObjectParamsSchema.extend({ pluginId: pluginParamsSchema.shape.pluginId }) },
    response: { description: "Plugin membership removed successfully.", status: 204 },
    tag: "Config Objects",
  },
  listConfigObjectAccess: {
    audience: "admin",
    description: "List direct, team, and org-wide grants for a config object.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectAccess,
    request: { params: configObjectParamsSchema },
    response: { description: "Config object access grants.", schema: accessGrantListResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  grantConfigObjectAccess: {
    audience: "admin",
    description: "Create one direct, team, or org-wide access grant for a config object.",
    method: "POST",
    path: pluginArchRoutePaths.configObjectAccess,
    request: { body: resourceAccessGrantWriteSchema, params: configObjectParamsSchema },
    response: { description: "Config object access grant created successfully.", schema: accessGrantMutationResponseSchema, status: 201 },
    tag: "Config Objects",
  },
  revokeConfigObjectAccess: {
    audience: "admin",
    description: "Soft-revoke one config object access grant.",
    method: "DELETE",
    path: pluginArchRoutePaths.configObjectAccessGrant,
    request: { params: configObjectAccessGrantParamsSchema },
    response: { description: "Config object access grant revoked successfully.", status: 204 },
    tag: "Config Objects",
  },
  listConfigObjectVersions: {
    audience: "admin",
    description: "List immutable versions for a config object.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectVersions,
    request: { params: configObjectParamsSchema, query: configObjectVersionListQuerySchema },
    response: { description: "Config object versions.", schema: configObjectVersionListResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  getConfigObjectVersion: {
    audience: "admin",
    description: "Get one immutable config object version.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectVersion,
    request: { params: configObjectVersionParamsSchema },
    response: { description: "Config object version detail.", schema: configObjectVersionDetailResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  getLatestConfigObjectVersion: {
    audience: "admin",
    description: "Resolve the latest config object version using created_at and id ordering.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectLatestVersion,
    request: { params: configObjectParamsSchema },
    response: { description: "Latest config object version detail.", schema: configObjectVersionDetailResponseSchema, status: 200 },
    tag: "Config Objects",
  },
  listPlugins: {
    audience: "admin",
    description: "List accessible plugins for the organization.",
    method: "GET",
    path: pluginArchRoutePaths.plugins,
    request: { query: pluginListQuerySchema },
    response: { description: "Plugin list.", schema: pluginListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  getPlugin: {
    audience: "admin",
    description: "Get one plugin and its current metadata.",
    method: "GET",
    path: pluginArchRoutePaths.plugin,
    request: { params: pluginParamsSchema },
    response: { description: "Plugin detail.", schema: pluginDetailResponseSchema, status: 200 },
    tag: "Plugins",
  },
  createPlugin: {
    audience: "member",
    description: "Create a private-by-default plugin, optionally bundled with components, org-wide sharing, and marketplace publishing.",
    method: "POST",
    path: pluginArchRoutePaths.plugins,
    request: { body: pluginCreateSchema },
    response: { description: "Plugin created successfully.", schema: pluginMutationResponseSchema, status: 201 },
    tag: "Plugins",
  },
  updatePlugin: {
    audience: "admin",
    description: "Patch plugin metadata.",
    method: "PATCH",
    path: pluginArchRoutePaths.plugin,
    request: { body: pluginUpdateSchema, params: pluginParamsSchema },
    response: { description: "Plugin updated successfully.", schema: pluginMutationResponseSchema, status: 200 },
    tag: "Plugins",
  },
  archivePlugin: {
    audience: "admin",
    description: "Archive a plugin without deleting membership history.",
    method: "POST",
    path: pluginArchRoutePaths.pluginArchive,
    request: { params: pluginParamsSchema },
    response: { description: "Archived plugin detail.", schema: pluginMutationResponseSchema, status: 200 },
    tag: "Plugins",
  },
  restorePlugin: {
    audience: "admin",
    description: "Restore an archived or deleted plugin.",
    method: "POST",
    path: pluginArchRoutePaths.pluginRestore,
    request: { params: pluginParamsSchema },
    response: { description: "Restored plugin detail.", schema: pluginMutationResponseSchema, status: 200 },
    tag: "Plugins",
  },
  listPluginConfigObjects: {
    audience: "admin",
    description: "List plugin memberships and the current config object projections they reference.",
    method: "GET",
    path: pluginArchRoutePaths.pluginConfigObjects,
    request: { params: pluginParamsSchema },
    response: { description: "Plugin memberships.", schema: pluginMembershipListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  addPluginConfigObject: {
    audience: "admin",
    description: "Add a config object to a plugin using plugin-scoped write access.",
    method: "POST",
    path: pluginArchRoutePaths.pluginConfigObjects,
    request: { body: pluginMembershipWriteSchema, params: pluginParamsSchema },
    response: { description: "Plugin membership created successfully.", schema: pluginMembershipMutationResponseSchema, status: 201 },
    tag: "Plugins",
  },
  removePluginConfigObject: {
    audience: "admin",
    description: "Remove one config object membership from a plugin.",
    method: "DELETE",
    path: pluginArchRoutePaths.pluginConfigObject,
    request: { params: pluginConfigObjectParamsSchema },
    response: { description: "Plugin membership removed successfully.", status: 204 },
    tag: "Plugins",
  },
  getResolvedPlugin: {
    audience: "admin",
    description: "Preview the resolved latest-version members of a plugin without invoking delivery.",
    method: "GET",
    path: pluginArchRoutePaths.pluginResolved,
    request: { params: pluginParamsSchema },
    response: { description: "Resolved plugin membership view.", schema: pluginMembershipListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  configurePluginMcpRequirement: {
    audience: "admin",
    description: "Configure one declared remote MCP server from a plugin by deriving its URL and audience server-side.",
    method: "POST",
    path: pluginArchRoutePaths.pluginMcpConnections,
    request: { body: pluginMcpRequirementConfigureSchema, params: pluginParamsSchema },
    response: { description: "Plugin MCP requirement connection configured successfully.", schema: pluginMcpRequirementConfigureResponseSchema, status: 200 },
    tag: "Plugins",
  },
  listPluginAccess: {
    audience: "admin",
    description: "List direct, team, and org-wide grants for a plugin.",
    method: "GET",
    path: pluginArchRoutePaths.pluginAccess,
    request: { params: pluginParamsSchema },
    response: { description: "Plugin access grants.", schema: accessGrantListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  listMePluginAccess: {
    audience: "member",
    description: "List the caller's effective plugin library with all applicable access edges.",
    method: "GET",
    path: pluginArchRoutePaths.mePluginAccess,
    response: { description: "Effective member plugin access.", schema: mePluginAccessListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  listMeLibrary: {
    audience: "member",
    description: "List the plugins and connections the caller can use with all applicable access edges.",
    method: "GET",
    path: pluginArchRoutePaths.meLibrary,
    response: { description: "Effective member library.", schema: meLibraryListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  listTeamPluginAccess: {
    audience: "member",
    description: "List the plugins a team can use through direct, marketplace, and organization-wide access.",
    method: "GET",
    path: pluginArchRoutePaths.teamPluginAccess,
    request: { params: teamParamsSchema },
    response: { description: "Effective plugin access for the team.", schema: teamPluginAccessListResponseSchema, status: 200 },
    tag: "Plugins",
  },
  grantPluginAccess: {
    audience: "admin",
    description: "Create one direct, team, or org-wide access grant for a plugin.",
    method: "POST",
    path: pluginArchRoutePaths.pluginAccess,
    request: { body: resourceAccessGrantWriteSchema, params: pluginParamsSchema },
    response: { description: "Plugin access grant created successfully.", schema: accessGrantMutationResponseSchema, status: 201 },
    tag: "Plugins",
  },
  revokePluginAccess: {
    audience: "admin",
    description: "Soft-revoke one plugin access grant.",
    method: "DELETE",
    path: pluginArchRoutePaths.pluginAccessGrant,
    request: { params: pluginAccessGrantParamsSchema },
    response: { description: "Plugin access grant revoked successfully.", status: 204 },
    tag: "Plugins",
  },
  listMarketplaces: {
    audience: "admin",
    description: "List accessible marketplaces for the organization.",
    method: "GET",
    path: pluginArchRoutePaths.marketplaces,
    request: { query: marketplaceListQuerySchema },
    response: { description: "Marketplace list.", schema: marketplaceListResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  getMarketplace: {
    audience: "admin",
    description: "Get one marketplace and its current metadata.",
    method: "GET",
    path: pluginArchRoutePaths.marketplace,
    request: { params: marketplaceParamsSchema },
    response: { description: "Marketplace detail.", schema: marketplaceDetailResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  createMarketplace: {
    audience: "admin",
    description: "Create a private-by-default marketplace. Most organizations need only one: list existing marketplaces first and prefer attaching plugins to an existing marketplace; only create a new one when explicitly asked.",
    method: "POST",
    path: pluginArchRoutePaths.marketplaces,
    request: { body: marketplaceCreateSchema },
    response: { description: "Marketplace created successfully.", schema: marketplaceMutationResponseSchema, status: 201 },
    tag: "Marketplaces",
  },
  updateMarketplace: {
    audience: "admin",
    description: "Patch marketplace metadata.",
    method: "PATCH",
    path: pluginArchRoutePaths.marketplace,
    request: { body: marketplaceUpdateSchema, params: marketplaceParamsSchema },
    response: { description: "Marketplace updated successfully.", schema: marketplaceMutationResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  archiveMarketplace: {
    audience: "admin",
    description: "Archive a marketplace without deleting membership history.",
    method: "POST",
    path: pluginArchRoutePaths.marketplaceArchive,
    request: { params: marketplaceParamsSchema },
    response: { description: "Archived marketplace detail.", schema: marketplaceMutationResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  deleteMarketplace: {
    audience: "admin",
    description: "Permanently delete a custom marketplace and its access and plugin relationships.",
    method: "POST",
    path: pluginArchRoutePaths.marketplaceDelete,
    request: { params: marketplaceParamsSchema },
    response: { description: "Snapshot of the deleted marketplace.", schema: marketplaceMutationResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  restoreMarketplace: {
    audience: "admin",
    description: "Restore an archived or deleted marketplace.",
    method: "POST",
    path: pluginArchRoutePaths.marketplaceRestore,
    request: { params: marketplaceParamsSchema },
    response: { description: "Restored marketplace detail.", schema: marketplaceMutationResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  listMarketplacePlugins: {
    audience: "admin",
    description: "List marketplace memberships and the plugins they reference.",
    method: "GET",
    path: pluginArchRoutePaths.marketplacePlugins,
    request: { params: marketplaceParamsSchema },
    response: { description: "Marketplace plugin memberships.", schema: marketplacePluginListResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  getMarketplaceResolved: {
    audience: "admin",
    description: "Return marketplace detail with plugins and derived source info.",
    method: "GET",
    path: pluginArchRoutePaths.marketplaceResolved,
    request: { params: marketplaceParamsSchema },
    response: { description: "Marketplace resolved detail.", schema: marketplaceResolvedResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  addMarketplacePlugin: {
    audience: "admin",
    description: "Add a plugin to a marketplace using marketplace-scoped write access.",
    method: "POST",
    path: pluginArchRoutePaths.marketplacePlugins,
    request: { body: marketplacePluginWriteSchema, params: marketplaceParamsSchema },
    response: { description: "Marketplace plugin membership created successfully.", schema: marketplacePluginMutationResponseSchema, status: 201 },
    tag: "Marketplaces",
  },
  removeMarketplacePlugin: {
    audience: "admin",
    description: "Remove one plugin membership from a marketplace.",
    method: "DELETE",
    path: pluginArchRoutePaths.marketplacePlugin,
    request: { params: marketplacePluginParamsSchema },
    response: { description: "Marketplace plugin membership removed successfully.", status: 204 },
    tag: "Marketplaces",
  },
  listMarketplaceAccess: {
    audience: "admin",
    description: "List direct, team, and org-wide grants for a marketplace.",
    method: "GET",
    path: pluginArchRoutePaths.marketplaceAccess,
    request: { params: marketplaceParamsSchema },
    response: { description: "Marketplace access grants.", schema: accessGrantListResponseSchema, status: 200 },
    tag: "Marketplaces",
  },
  grantMarketplaceAccess: {
    audience: "admin",
    description: "Create one direct, team, or org-wide access grant for a marketplace.",
    method: "POST",
    path: pluginArchRoutePaths.marketplaceAccess,
    request: { body: resourceAccessGrantWriteSchema, params: marketplaceParamsSchema },
    response: { description: "Marketplace access grant created successfully.", schema: accessGrantMutationResponseSchema, status: 201 },
    tag: "Marketplaces",
  },
  revokeMarketplaceAccess: {
    audience: "admin",
    description: "Soft-revoke one marketplace access grant.",
    method: "DELETE",
    path: pluginArchRoutePaths.marketplaceAccessGrant,
    request: { params: marketplaceAccessGrantParamsSchema },
    response: { description: "Marketplace access grant revoked successfully.", status: 204 },
    tag: "Marketplaces",
  },
  listConnectorAccounts: {
    audience: "admin",
    description: "List connector accounts such as GitHub App installations available to the org.",
    method: "GET",
    path: pluginArchRoutePaths.connectorAccounts,
    request: { query: connectorAccountListQuerySchema },
    response: { description: "Connector account list.", schema: connectorAccountListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  createConnectorAccount: {
    audience: "admin",
    description: "Create a reusable connector account record.",
    method: "POST",
    path: pluginArchRoutePaths.connectorAccounts,
    request: { body: connectorAccountCreateSchema },
    response: { description: "Connector account created successfully.", schema: connectorAccountMutationResponseSchema, status: 201 },
    tag: "Connectors",
  },
  getConnectorAccount: {
    audience: "admin",
    description: "Get one connector account record.",
    method: "GET",
    path: pluginArchRoutePaths.connectorAccount,
    request: { params: connectorAccountParamsSchema },
    response: { description: "Connector account detail.", schema: connectorAccountDetailResponseSchema, status: 200 },
    tag: "Connectors",
  },
  disconnectConnectorAccount: {
    audience: "admin",
    description: "Disconnect one connector account and delete its connector-managed imports (mappings, config objects, plugins created via discovery, and empty marketplaces).",
    method: "POST",
    path: pluginArchRoutePaths.connectorAccountDisconnect,
    request: { body: connectorAccountDisconnectSchema, params: connectorAccountParamsSchema },
    response: { description: "Connector account disconnected and cleaned up successfully.", schema: connectorAccountDisconnectResponseSchema, status: 200 },
    tag: "Connectors",
  },
  listConnectorInstances: {
    audience: "admin",
    description: "List configured connector instances for the org.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstances,
    request: { query: connectorInstanceListQuerySchema },
    response: { description: "Connector instance list.", schema: connectorInstanceListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  createConnectorInstance: {
    audience: "admin",
    description: "Create a connector instance backed by one connector account.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstances,
    request: { body: connectorInstanceCreateSchema },
    response: { description: "Connector instance created successfully.", schema: connectorInstanceMutationResponseSchema, status: 201 },
    tag: "Connectors",
  },
  getConnectorInstance: {
    audience: "admin",
    description: "Get one connector instance.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstance,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance detail.", schema: connectorInstanceDetailResponseSchema, status: 200 },
    tag: "Connectors",
  },
  updateConnectorInstance: {
    audience: "admin",
    description: "Patch connector instance metadata or config.",
    method: "PATCH",
    path: pluginArchRoutePaths.connectorInstance,
    request: { body: connectorInstanceUpdateSchema, params: connectorInstanceParamsSchema },
    response: { description: "Connector instance updated successfully.", schema: connectorInstanceMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  archiveConnectorInstance: {
    audience: "admin",
    description: "Archive a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceArchive,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance archived successfully.", schema: connectorInstanceMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  getConnectorInstanceConfiguration: {
    audience: "admin",
    description: "Return the configured plugins, mappings, and import state for a connector instance.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstanceConfiguration,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance configuration returned successfully.", schema: connectorInstanceConfigurationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  setConnectorInstanceAutoImport: {
    audience: "admin",
    description: "Enable or disable auto-import of new plugins for a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceAutoImport,
    request: { body: connectorInstanceAutoImportSchema, params: connectorInstanceParamsSchema },
    response: { description: "Connector instance auto-import updated successfully.", schema: connectorInstanceConfigurationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  removeConnectorInstance: {
    audience: "admin",
    description: "Remove a connector instance and delete its associated plugins, mappings, config objects, and bindings.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceRemove,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance removed and cleaned up successfully.", schema: connectorInstanceRemoveResponseSchema, status: 200 },
    tag: "Connectors",
  },
  disableConnectorInstance: {
    audience: "admin",
    description: "Disable sync execution for a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceDisable,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance disabled successfully.", schema: connectorInstanceMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  enableConnectorInstance: {
    audience: "admin",
    description: "Re-enable sync execution for a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceEnable,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance enabled successfully.", schema: connectorInstanceMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  listConnectorInstanceAccess: {
    audience: "admin",
    description: "List direct, team, and org-wide grants for a connector instance.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstanceAccess,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance access grants.", schema: accessGrantListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  grantConnectorInstanceAccess: {
    audience: "admin",
    description: "Create one direct, team, or org-wide access grant for a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceAccess,
    request: { body: resourceAccessGrantWriteSchema, params: connectorInstanceParamsSchema },
    response: { description: "Connector instance access grant created successfully.", schema: accessGrantMutationResponseSchema, status: 201 },
    tag: "Connectors",
  },
  revokeConnectorInstanceAccess: {
    audience: "admin",
    description: "Soft-revoke one connector instance access grant.",
    method: "DELETE",
    path: pluginArchRoutePaths.connectorInstanceAccessGrant,
    request: { params: connectorInstanceAccessGrantParamsSchema },
    response: { description: "Connector instance access grant revoked successfully.", status: 204 },
    tag: "Connectors",
  },
  listConnectorTargets: {
    audience: "admin",
    description: "List external targets configured under a connector instance.",
    method: "GET",
    path: pluginArchRoutePaths.connectorTargets,
    request: { params: connectorInstanceParamsSchema, query: connectorTargetListQuerySchema },
    response: { description: "Connector target list.", schema: connectorTargetListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  createConnectorTarget: {
    audience: "admin",
    description: "Create one connector target such as a GitHub repository branch.",
    method: "POST",
    path: pluginArchRoutePaths.connectorTargets,
    request: { body: connectorTargetCreateSchema, params: connectorInstanceParamsSchema },
    response: { description: "Connector target created successfully.", schema: connectorTargetMutationResponseSchema, status: 201 },
    tag: "Connectors",
  },
  getConnectorTarget: {
    audience: "admin",
    description: "Get one connector target.",
    method: "GET",
    path: pluginArchRoutePaths.connectorTarget,
    request: { params: connectorTargetParamsSchema },
    response: { description: "Connector target detail.", schema: connectorTargetDetailResponseSchema, status: 200 },
    tag: "Connectors",
  },
  updateConnectorTarget: {
    audience: "admin",
    description: "Patch one connector target.",
    method: "PATCH",
    path: pluginArchRoutePaths.connectorTarget,
    request: { body: connectorTargetUpdateSchema, params: connectorTargetParamsSchema },
    response: { description: "Connector target updated successfully.", schema: connectorTargetMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  resyncConnectorTarget: {
    audience: "admin",
    description: "Queue a manual reconciliation run for one connector target.",
    method: "POST",
    path: pluginArchRoutePaths.connectorTargetResync,
    request: { params: connectorTargetParamsSchema },
    response: { description: "Connector target resync queued successfully.", schema: connectorSyncAsyncResponseSchema, status: 202 },
    tag: "Connectors",
  },
  listConnectorMappings: {
    audience: "admin",
    description: "List mappings configured under a connector target.",
    method: "GET",
    path: pluginArchRoutePaths.connectorTargetMappings,
    request: { params: connectorTargetParamsSchema, query: connectorMappingListQuerySchema },
    response: { description: "Connector mapping list.", schema: connectorMappingListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  createConnectorMapping: {
    audience: "admin",
    description: "Create a path or API mapping for a connector target.",
    method: "POST",
    path: pluginArchRoutePaths.connectorTargetMappings,
    request: { body: connectorMappingCreateSchema, params: connectorTargetParamsSchema },
    response: { description: "Connector mapping created successfully.", schema: connectorMappingMutationResponseSchema, status: 201 },
    tag: "Connectors",
  },
  updateConnectorMapping: {
    audience: "admin",
    description: "Patch one connector mapping.",
    method: "PATCH",
    path: pluginArchRoutePaths.connectorMapping,
    request: { body: connectorMappingUpdateSchema, params: connectorMappingParamsSchema },
    response: { description: "Connector mapping updated successfully.", schema: connectorMappingMutationResponseSchema, status: 200 },
    tag: "Connectors",
  },
  deleteConnectorMapping: {
    audience: "admin",
    description: "Delete one connector mapping.",
    method: "DELETE",
    path: pluginArchRoutePaths.connectorMapping,
    request: { params: connectorMappingParamsSchema },
    response: { description: "Connector mapping deleted successfully.", status: 204 },
    tag: "Connectors",
  },
  listConnectorSyncEvents: {
    audience: "admin",
    description: "List connector sync events for inspection and debugging.",
    method: "GET",
    path: pluginArchRoutePaths.connectorSyncEvents,
    request: { query: connectorSyncEventListQuerySchema },
    response: { description: "Connector sync event list.", schema: connectorSyncEventListResponseSchema, status: 200 },
    tag: "Connectors",
  },
  getConnectorSyncEvent: {
    audience: "admin",
    description: "Get one connector sync event.",
    method: "GET",
    path: pluginArchRoutePaths.connectorSyncEvent,
    request: { params: connectorSyncEventParamsSchema },
    response: { description: "Connector sync event detail.", schema: connectorSyncEventDetailResponseSchema, status: 200 },
    tag: "Connectors",
  },
  retryConnectorSyncEvent: {
    audience: "admin",
    description: "Queue a retry for a failed or partial connector sync event.",
    method: "POST",
    path: pluginArchRoutePaths.connectorSyncEventRetry,
    request: { params: connectorSyncEventParamsSchema },
    response: { description: "Connector sync retry queued successfully.", schema: connectorSyncAsyncResponseSchema, status: 202 },
    tag: "Connectors",
  },
  connectorInstanceSyncNow: {
    audience: "admin",
    description: "Queue sync work for every idle target in a connector instance.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceSyncNow,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "Connector instance sync queued successfully.", schema: connectorInstanceSyncNowResponseSchema, status: 200 },
    tag: "Connectors",
  },
  getGithubConnectorDiscovery: {
    audience: "admin",
    description: "Analyze a GitHub connector instance and return the discovered repository shape and plugin candidates.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstanceDiscovery,
    request: { params: connectorInstanceParamsSchema },
    response: { description: "GitHub connector discovery returned successfully.", schema: githubConnectorDiscoveryResponseSchema, status: 200 },
    tag: "GitHub",
  },
  listGithubConnectorDiscoveryTree: {
    audience: "admin",
    description: "Page through the normalized GitHub repository tree for one connector instance.",
    method: "GET",
    path: pluginArchRoutePaths.connectorInstanceDiscoveryTree,
    request: { params: connectorInstanceParamsSchema, query: githubDiscoveryTreeQuerySchema },
    response: { description: "GitHub discovery tree page returned successfully.", schema: githubDiscoveryTreeResponseSchema, status: 200 },
    tag: "GitHub",
  },
  applyGithubConnectorDiscovery: {
    audience: "admin",
    description: "Create OmniRush.ai plugins and connector mappings from selected GitHub discovery candidates.",
    method: "POST",
    path: pluginArchRoutePaths.connectorInstanceDiscoveryApply,
    request: { body: githubDiscoveryApplySchema, params: connectorInstanceParamsSchema },
    response: { description: "GitHub discovery selection applied successfully.", schema: githubDiscoveryApplyResponseSchema, status: 200 },
    tag: "GitHub",
  },
  githubInstallStart: {
    audience: "admin",
    description: "Start the GitHub App install flow and return a redirect URL.",
    method: "POST",
    path: pluginArchRoutePaths.githubInstallStart,
    request: { body: githubInstallStartSchema },
    response: { description: "GitHub install redirect created successfully.", schema: githubInstallStartResponseSchema, status: 200 },
    tag: "GitHub",
  },
  githubInstallComplete: {
    audience: "admin",
    description: "Complete one GitHub App installation and return repositories visible to it.",
    method: "POST",
    path: pluginArchRoutePaths.githubInstallComplete,
    request: { body: githubInstallCompleteSchema },
    response: { description: "GitHub installation completed successfully.", schema: githubInstallCompleteResponseSchema, status: 200 },
    tag: "GitHub",
  },
  githubSetup: {
    audience: "admin",
    description: "Create the GitHub connector account, instance, target, and initial mappings in one setup flow.",
    method: "POST",
    path: pluginArchRoutePaths.githubSetup,
    request: { body: githubConnectorSetupSchema },
    response: { description: "GitHub connector setup created successfully.", schema: githubSetupResponseSchema, status: 201 },
    tag: "GitHub",
  },
  githubCreateAccount: {
    audience: "admin",
    description: "Persist a GitHub App installation as a reusable connector account.",
    method: "POST",
    path: pluginArchRoutePaths.githubAccounts,
    request: { body: githubConnectorAccountCreateSchema },
    response: { description: "GitHub connector account created successfully.", schema: connectorAccountMutationResponseSchema, status: 201 },
    tag: "GitHub",
  },
  githubListRepositories: {
    audience: "admin",
    description: "List repositories visible to one GitHub connector account.",
    method: "GET",
    path: pluginArchRoutePaths.githubAccountRepositories,
    request: { params: connectorAccountRepositoryParamsSchema, query: githubRepositoryListQuerySchema },
    response: { description: "GitHub repositories visible to the installation.", schema: githubRepositoryListResponseSchema, status: 200 },
    tag: "GitHub",
  },
  githubValidateTarget: {
    audience: "admin",
    description: "Validate one GitHub repository-branch target before persisting it.",
    method: "POST",
    path: pluginArchRoutePaths.githubValidateTarget,
    request: { body: githubValidateTargetSchema },
    response: { description: "GitHub target validation result.", schema: githubValidateTargetResponseSchema, status: 200 },
    tag: "GitHub",
  },
  githubWebhookIngress: {
    audience: "public_webhook",
    description: "Accept a GitHub App webhook delivery, verify the raw-body signature, and enqueue any relevant sync work.",
    method: "POST",
    path: pluginArchRoutePaths.githubWebhookIngress,
    request: { body: githubWebhookRawBodySchema, headers: githubWebhookHeadersSchema },
    response: { description: "Valid webhook accepted or ignored.", schema: githubWebhookAcceptedResponseSchema.or(githubWebhookIgnoredResponseSchema), status: 202 },
    tag: "Webhooks",
  },
}

export const deferredPluginArchEndpointContracts: DeferredEndpointContract[] = [
  {
    description: "Compare two config object versions.",
    method: "GET",
    path: pluginArchRoutePaths.configObjectCompareVersions,
    reason: "Diff semantics can wait until immutable version storage exists.",
    tag: "Config Objects",
  },
  {
    description: "Type-specific convenience endpoints for skills.",
    method: "GET",
    path: pluginArchRoutePaths.skills,
    reason: "Shared config-object routes land first; per-type wrappers follow once the core surface is working.",
    tag: "Config Objects",
  },
  {
    description: "Type-specific convenience endpoints for agents.",
    method: "GET",
    path: pluginArchRoutePaths.agents,
    reason: "Shared config-object routes land first; per-type wrappers follow once the core surface is working.",
    tag: "Config Objects",
  },
  {
    description: "Type-specific convenience endpoints for commands.",
    method: "GET",
    path: pluginArchRoutePaths.commands,
    reason: "Shared config-object routes land first; per-type wrappers follow once the core surface is working.",
    tag: "Config Objects",
  },
  {
    description: "Type-specific convenience endpoints for tools.",
    method: "GET",
    path: pluginArchRoutePaths.tools,
    reason: "Shared config-object routes land first; per-type wrappers follow once the core surface is working.",
    tag: "Config Objects",
  },
  {
    description: "Type-specific convenience endpoints for MCPs.",
    method: "GET",
    path: pluginArchRoutePaths.mcps,
    reason: "Shared config-object routes land first; per-type wrappers follow once the core surface is working.",
    tag: "Config Objects",
  },
  {
    description: "Create and list plugin releases.",
    method: "POST",
    path: pluginArchRoutePaths.pluginReleases,
    reason: "Delivery and release snapshots stay deferred until the admin and webhook slice is live.",
    tag: "Plugins",
  },
  {
    description: "Preview one connector mapping against remote source data.",
    method: "POST",
    path: pluginArchRoutePaths.connectorMappingPreview,
    reason: "Mapping preview depends on the later reconciliation engine and should not block the first admin slice.",
    tag: "Connectors",
  },
]

export const pluginArchContractSummary = {
  implementationHome: {
    adminApi: "ee/apps/den-api/src/routes/org",
    persistence: "ee/packages/den-db/src/schema",
    webhookIngress: "ee/apps/den-api/src/routes",
  },
  outOfScope: [
    "plugin delivery/install endpoints",
    "plugin release snapshot implementation",
    "type-specific convenience wrappers",
  ],
} as const