# NOTE: Внутренний контракт ядро ↔ коннекторы. Не публикуется наружу.
# Соответствует Go interface `connector.Connector` в коде. См. 30-services/ingestion/connectors/AGENTS.md.

# Это псевдо-OpenAPI описание Go-интерфейса для документации/onboarding'а.
# Канонический источник — Go interface в `core/connector/contract.go`.

asyncapi: 3.0.0
info:
  title: Connector ↔ Core internal contract
  version: 1.0.0-draft

components:
  schemas:
    ConnectorContract:
      type: object
      description: |
        Каждый коннектор реализует следующие методы:
      properties:
        Validate:
          type: object
          description: |
            Validate(ctx, credential) → (ValidationResult, error)
            Проверяет работоспособность credential через тестовый запрос.
        FetchCatalog:
          type: object
          description: |
            FetchCatalog(ctx, credential, opts) → (CatalogStream, error)
            Полная или инкрементальная выгрузка номенклатуры.
        FetchObservation:
          type: object
          description: |
            FetchObservation(ctx, credential, supplier_sku) → (Observation, error)
            Цена / остаток / условия для конкретного SKU.
        DescribeAuth:
          type: object
          description: |
            DescribeAuth() → AuthSchema
            Возвращает JSON Schema полей auth_payload (используется UI кабинета).
        Capabilities:
          type: object
          description: |
            Capabilities() → []Capability
            Что коннектор умеет: catalog/prices/stock/place_orders/webhooks.

# Canonical Go interface (referenced):
#
#  type Connector interface {
#      Validate(ctx context.Context, cred Credential) (ValidationResult, error)
#      FetchCatalog(ctx context.Context, cred Credential, opts CatalogOpts) (CatalogStream, error)
#      FetchObservation(ctx context.Context, cred Credential, supplierSKU string) (Observation, error)
#      DescribeAuth() AuthSchema
#      Capabilities() []Capability
#  }
