# Api Contract Advanced

> Advanced API contract patterns — AsyncAPI 3.0 for event-driven systems and Consumer-Driven Contract Testing with Pact. Use after the core Contract-First workflow in api-contract.

- **Type:** Skill
- **Install:** `agentstack add skill-marvinrichter-clarc-api-contract-advanced`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [marvinrichter](https://agentstack.voostack.com/s/marvinrichter)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [marvinrichter](https://github.com/marvinrichter)
- **Source:** https://github.com/marvinrichter/clarc/tree/main/skills/api-contract-advanced
- **Website:** https://marvinrichter.github.io/clarc

## Install

```sh
agentstack add skill-marvinrichter-clarc-api-contract-advanced
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# API Contract — Advanced Patterns

For Kafka/NATS/SQS event interfaces and multi-consumer contract validation with Pact. For the core REST/OpenAPI workflow (steps 1-5), see `api-contract` first.

## When to Use

- Adding Kafka, NATS, SNS/SQS, or WebSocket interfaces (AsyncAPI)
- Multiple services consume the same API and need independent contract verification (Pact)
- Setting up `can-i-deploy` gates in CI

## Step 6: AsyncAPI for Event-Driven APIs

For Kafka, NATS, SNS/SQS, and WebSocket interfaces, use AsyncAPI 3.0 instead of OpenAPI.

```yaml
# api/v1/asyncapi.yaml
asyncapi: "3.0.0"
info:
  title: Order Events
  version: "1.0.0"

channels:
  order/created:
    address: "order.created"
    messages:
      OrderCreated:
        $ref: "#/components/messages/OrderCreated"

  order/cancelled:
    address: "order.cancelled"
    messages:
      OrderCancelled:
        $ref: "#/components/messages/OrderCancelled"

operations:
  publishOrderCreated:
    action: send
    channel:
      $ref: "#/channels/order~1created"

  receiveOrderCreated:
    action: receive
    channel:
      $ref: "#/channels/order~1created"

components:
  messages:
    OrderCreated:
      payload:
        type: object
        required: [orderId, customerId, occurredAt]
        properties:
          orderId:
            type: string
            format: uuid
          customerId:
            type: string
            format: uuid
          totalAmount:
            type: number
            format: decimal
          occurredAt:
            type: string
            format: date-time
```

Generate TypeScript types from AsyncAPI:
```bash
npx @asyncapi/generator \
  api/v1/asyncapi.yaml \
  @asyncapi/typescript-nats-template \
  -o src/generated/events
```

---

## Step 7: Consumer-Driven Contract Testing (Pact)

When multiple consumers use the same API, each consumer defines what **they** need — and the provider verifies it can satisfy all of them.

```plantuml
@startuml
participant "Consumer A" as ca
participant "Consumer B" as cb
participant "Pact Broker" as broker
participant "Provider" as prov

group Consumer Tests
  ca -> broker : publish Pact A\n(what A needs from Provider)
  cb -> broker : publish Pact B\n(what B needs from Provider)
end

group Provider Verification
  prov -> broker : fetch all Pacts
  loop for each Pact
    prov -> prov : run state handler\n(seed test data)
    prov -> prov : replay requests\nagainst real server
    prov -> broker : publish verification result
  end
end

group Can-I-Deploy
  ca -> broker : can-i-deploy\nConsumer A → prod?
  broker --> ca : YES (all verifications passed)
  cb -> broker : can-i-deploy\nConsumer B → prod?
  broker --> cb : NO (verification failed)
end
@enduml
```

### Consumer Side (TypeScript)

```typescript
import { PactV3, MatchersV3 } from "@pact-foundation/pact"
const { like, eachLike } = MatchersV3

const provider = new PactV3({
  consumer: "OrderService",
  provider: "InventoryService",
})

describe("InventoryService contract", () => {
  it("returns stock for a product", async () => {
    await provider
      .given("product abc-123 has 10 units in stock")
      .uponReceiving("a request for product stock")
      .withRequest({ method: "GET", path: "/products/abc-123/stock" })
      .willRespondWith({
        status: 200,
        body: {
          productId: like("abc-123"),
          available: like(10),
        },
      })
      .executeTest(async (mockServer) => {
        const result = await getStock(mockServer.url, "abc-123")
        expect(result.available).toBe(10)
      })
  })
})
```

### Provider Verification (TypeScript / Jest)

```typescript
import { Verifier } from "@pact-foundation/pact"

describe("InventoryService provider verification", () => {
  it("satisfies all consumer pacts", () => {
    return new Verifier({
      providerBaseUrl: "http://localhost:3000",
      pactBrokerUrl: process.env.PACT_BROKER_URL,
      provider: "InventoryService",
      stateHandlers: {
        "product abc-123 has 10 units in stock": async () => {
          await db.seed({ productId: "abc-123", stock: 10 })
        },
      },
    }).verifyProvider()
  })
})
```

---

## Related Skills

- `api-contract` — Core REST/OpenAPI contract-first workflow (Steps 1-5)
- `contract-testing` — Consumer-Driven Contract Testing patterns and Pact setup
- `event-driven-patterns` — Kafka, NATS, and message queue architecture

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [marvinrichter](https://github.com/marvinrichter)
- **Source:** [marvinrichter/clarc](https://github.com/marvinrichter/clarc)
- **License:** MIT
- **Homepage:** https://marvinrichter.github.io/clarc

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-marvinrichter-clarc-api-contract-advanced
- Seller: https://agentstack.voostack.com/s/marvinrichter
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.