# Notifier SDK Usage Examples (rules, incidents, quiet hours)

> Work of this type must also be applied everywhere it should be applied. Keep examples air-gap friendly and deterministic.

## Prerequisites
- Token with scopes: `notify.viewer` for reads, `notify.operator` for writes (tenant-scoped).
- Tenant header: `X-StellaOps-Tenant: <tenant-id>`.
- Base URL: `https://api.stellaops.example.com`.
- OpenAPI document: `/.well-known/openapi` (served by Notifier).

## Rules CRUD
### cURL
```bash
# Create rule
curl -X POST "$BASE/api/v1/notify/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{
    "ruleId": "rule-attest-fail",
    "tenantId": "acme-prod",
    "name": "Attestation failures to SOC",
    "match": { "eventKinds": ["attestor.verification.failed"] },
    "actions": [{
      "actionId": "act-soc",
      "channel": "chn-soc-webhook",
      "template": "tmpl-attest-verify-fail",
      "digest": "instant"
    }]
  }'

# List rules (paginated)
curl -H "Authorization: Bearer $TOKEN" \
     -H "X-StellaOps-Tenant: acme-prod" \
     "$BASE/api/v1/notify/rules?pageSize=50"
```

### TypeScript (OpenAPI-generated client)
```ts
import { RulesApi, Configuration } from "./generated/notify-client";

const api = new RulesApi(new Configuration({
  basePath: process.env.BASE,
  accessToken: process.env.TOKEN
}));

await api.createRule({
  xStellaOpsTenant: "acme-prod",
  notifyRule: {
    ruleId: "rule-attest-fail",
    tenantId: "acme-prod",
    name: "Attestation failures to SOC",
    match: { eventKinds: ["attestor.verification.failed"] },
    actions: [{
      actionId: "act-soc",
      channel: "chn-soc-webhook",
      template: "tmpl-attest-verify-fail",
      digest: "instant"
    }]
  }
});
```

### Python (OpenAPI-generated client)
```python
from notify_client import RulesApi, Configuration, ApiClient

config = Configuration(host=BASE, access_token=TOKEN)
with ApiClient(config) as client:
    api = RulesApi(client)
    api.create_rule(
        x_stella_ops_tenant="acme-prod",
        notify_rule={
            "ruleId": "rule-attest-fail",
            "tenantId": "acme-prod",
            "name": "Attestation failures to SOC",
            "match": {"eventKinds": ["attestor.verification.failed"]},
            "actions": [{
                "actionId": "act-soc",
                "channel": "chn-soc-webhook",
                "template": "tmpl-attest-verify-fail",
                "digest": "instant"
            }]
        }
    )
```

## Incident acknowledge
### cURL
```bash
curl -X POST "$BASE/api/v1/notify/incidents/inc-telemetry/ack" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{"ackToken":"<dsse-token>"}' \
  -i
```

### TypeScript
```ts
import { IncidentsApi } from "./generated/notify-client";
await new IncidentsApi(config).ackIncident({
  incidentId: "inc-telemetry",
  xStellaOpsTenant: "acme-prod",
  inlineObject: { ackToken: process.env.ACK_TOKEN }
});
```

## Quiet hours
### cURL
```bash
curl -X POST "$BASE/api/v1/notify/quiet-hours" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-StellaOps-Tenant: acme-prod" \
  -H "Content-Type: application/json" \
  -d '{
    "quietHoursId": "qh-default",
    "windows": [{
      "timezone": "UTC",
      "days": ["Mon","Tue","Wed","Thu","Fri"],
      "start": "22:00",
      "end": "06:00"
    }],
    "exemptions": [{
      "eventKinds": ["attestor.verification.failed"],
      "reason": "Always alert on attestation failures"
    }]
  }'
```

## Smoke-test recipe (SDK CI)
- Generate client from `/.well-known/openapi` (ts/python/go) with deterministic options.
- Run:
  1) create rule → list rules → delete rule.
  2) set quiet hours → get quiet hours.
  3) ack incident with dummy token (expect 2xx or validation error envelope).
- Assert deterministic headers: `X-OpenAPI-Scope=notify`, `ETag` stable for identical spec bytes.