# nexuscrm-connectors
> Integration runtime for NexusCRM connectors, webhooks, callouts, and named credentials.

Part of the **NexusCRM platform**, split by release boundary into L0 platform repos + L1 product packs + L2 tenant delivery. This repository is an **L0 platform integration module**.

## What this is
This is the integration concern of the platform — the runtime that connects NexusCRM to external systems. It owns inbound event ingestion and routing, webhook receipt and verification, outbound callouts, named-credential management, and the connector registry/runtime that ties them together (capabilities, health, throttling, sync state, ingress receipts). It exposes its operations through a REST interface layer over a set of feature services.

## Role in the L0 / L1 / L2 architecture
This is an L0 concern module: platform **mechanism** for talking to the outside world, not product or tenant shape. It speaks the neutral contract and stays out of the core domain engines. Connector recipes, product-specific mappings, and tenant wiring live above this layer; this repo provides the reusable integration primitives they build on.

## What belongs here
- Inbound connector event ingestion, routing, and reconciliation
- Webhook receipt, secret/verification, and dispatch
- Outbound callouts
- Named-credential storage and resolution
- Connector registry/runtime: capabilities, health, throttle, sync state, ingress receipts
- The REST interface layer that exposes the above

## What does NOT belong here
- Core domain engines (metadata, records, policy)
- Product pack JSON / dialect recipes
- Tenant deploy shape
- Backend server wiring or engine internals

## Public surface (key packages)
- `application/connectors` — connector application/orchestration services
- `features/connector/...` — connector runtime features: `callout`, `events`, `inbound`, `inboundrouting`, `capabilities`, `health`, `throttle`, `syncstate`, `ingressreceipts`, `packstate`
- `features/connector/oauth` — provider-neutral per-user OAuth/PKCE and generation-fenced token persistence
- `features/connector/delivery` — provider-neutral immutable-request and one-shot external-delivery fencing
- `features/namedcredential` — named-credential service
- `features/webhooks` — webhook receipt and handling
- `interfaces/rest` — REST entrypoints (`connectors`, `connector_webhooks`, `admin/namedcredentials`, `internal`)

## Dependency rules
- May depend on: `nexuscrm-contract` plus transport/HTTP libraries (gin, sql driver)
- Must NOT depend on: `backend`/internal host wiring or core engine internals

## How it is consumed
```go
require github.com/pingcap-inc/nexuscrm-connectors v0.2.0
```
Consumed by the backend and the controlplane to provide the platform's integration runtime.

WorkItem claim contexts may carry a normalized executor scope through
`workqueue.ClaimWorkTypes`. The latest WorkItem-only release intentionally
does not preserve the `v0.1.x` custom-service contract: production callers of
`NewWorkItemWorker` must pass their activation context and a service that
implements `WorkItemCutoverVerifier`. This fail-closes worker startup unless
the current controlplane receipt is attested; historical Event execution and
legacy custom-service admission are not supported.

## Release & versioning
Published private module, semver tags. The next WorkItem-only release is
`v0.2.0` because it intentionally breaks the v0.1.x constructor and custom
service admission contract; consumers must pin the matching tag.