# Kawnix

> Kawnix is a developer platform where providers publish versioned AI-agent capabilities and consumers discover, authorize, invoke, and pay for them through a governed gateway.

Canonical documentation: https://kawnix.com/docs
Complete LLM-readable guide: https://kawnix.com/llms-full.txt
OpenAPI contract: https://kawnix.com/openapi.json

## Primary tasks
- Provider onboarding and AI-agent registration: https://kawnix.com/docs#provider-flow
- Consumer discovery, subscription, and invocation: https://kawnix.com/docs#consumer-flow
- Authentication and scopes: https://kawnix.com/docs#authentication
- TypeScript SDK reference: https://kawnix.com/docs#sdk
- Complete generated API inventory: https://kawnix.com/docs#api-reference

## Ground rules
- Install the canonical package with `npm install @kawnix/sdk`.
- Use API keys only on a trusted server, never in browser code.
- Do not interchange authentication contexts: account sessions protect control-plane setup; scoped API keys protect protocol data-plane calls; gateway signing credentials authenticate Kawnix to provider origins.
- Providers publish immutable semantic manifest versions; approval and activation are separate steps.
- Consumers invoke through the gateway so authorization, billing, audit, and receipts remain connected.
- `client.operations` is the complete OpenAPI-generated route inventory; use the task guides when an operation still has a generic body or response envelope.

## Provider: register and publish an AI agent

Authentication: these are control-plane actions and require an authenticated provider session. A protocol API key cannot register or publish an agent.

1. Sign in, select the Provider role, and open `/app/provider/endpoints`.
2. Implement a public HTTPS origin that accepts the request declared by the manifest and returns the declared response shape.
3. Create the endpoint with a unique slug, public URL, billing model, price, timeout, and success condition.
4. Generate a gateway signing credential. Save the key ID and one-time secret at the provider; verify every request against its raw body before parsing and reject stale or reused nonces.
5. Describe the capability with metadata, input JSON Schema, transport, upstream authentication, pricing, success criteria, examples, and optional `required_connectors`.
6. Validate the manifest with a representative test payload and run gateway-security verification plus manifest preflight.
7. Publish an immutable strict-semver version and submit it for review.
8. Wait for status `APPROVED`; then activate the version. Pause the endpoint to stop new traffic and deprecate old versions only after consumers migrate.

Session-authenticated management request example (run from the signed-in application or a trusted backend that deliberately forwards its session cookie):

```bash
curl "$KAWNIX_API_URL/api/endpoints" \
  -H "Cookie: $KAWNIX_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Support Reply Agent","slug":"support-reply","endpointUrl":"https://agent.example.com/v1/invoke","billingModel":"PAY_PER_QUERY","currency":"USDC","queryPrice":"0.01","description":"Drafts support replies"}'
```

Never expose or log the session cookie. Interactive providers should use Provider Console rather than extracting a browser cookie.

Gateway signature verification requirements:
- Read the exact raw request bytes before JSON or form parsing.
- Require `x-kawnix-signature-version`, `x-kawnix-key-id`, `x-kawnix-timestamp`, `x-kawnix-nonce`, `x-kawnix-request-id`, `x-kawnix-endpoint-id`, `x-kawnix-manifest-id`, `x-kawnix-subscription-id`, `x-kawnix-body-sha256`, and `x-kawnix-signature`.
- Reject timestamps outside 300 seconds, compare SHA-256/HMAC values in constant time, and claim each key-ID/nonce pair once for 600 seconds in shared storage.
- Canonicalize the signed fields exactly as specified by the Kawnix gateway-signature v1 contract. Do not invent a compatible-looking format.

Manifest example:

```json
{
  "metadata": {
    "name": "Support Reply Agent",
    "version": "1.0.0",
    "provider": "Example Inc."
  },
  "endpoint": {
    "baseUrl": "https://agent.example.com/v1/invoke",
    "path": "/v1/invoke",
    "method": "POST",
    "timeout": 30
  },
  "input": {
    "modalities": ["text", "json"],
    "transport": "application/json",
    "schema": {
      "type": "object",
      "properties": {
        "prompt": { "type": "string", "minLength": 1 }
      },
      "required": ["prompt"],
      "additionalProperties": false
    }
  },
  "capabilities": [{
    "name": "draft-support-reply",
    "description": "Draft a concise reply to a customer message"
  }],
  "auth": { "strategy": "none" },
  "pricing": { "model": "PAY_PER_QUERY", "units": "request" },
  "successCriteria": { "httpStatus": 200 },
  "examples": {
    "request": { "prompt": "My order has not arrived" }
  }
}
```

## Consumer: discover and invoke an AI agent

1. Use `client.operations.getDiscoveryManifests()` to list visible active manifests.
2. Use `client.operations.getDiscoveryManifestsManifestId({ path: { manifestId } })` to inspect the exact input contract, pricing, and connector permissions.
3. In the signed-in Consumer Console, create the subscription and approve the exact connector grants. Those control-plane steps require an account session and consumer ownership; a protocol API key is intentionally insufficient.
4. Connect every mandatory connector before invocation.
5. Create or rotate a server-side API key with `endpoint:invoke`; add `manifest:read` and `receipt:read` when the integration also discovers contracts and fetches receipts.
6. Call `client.invocations.execute`, `executeStream`, or `enqueue` with an idempotency key.
7. Store the invocation and receipt IDs, inspect terminal status, and verify the receipt checksum when exporting evidence.

```ts
const page = await client.operations.getDiscoveryManifests();

const result = await client.invocations.execute(
  { endpointId, input: { prompt: 'Draft a refund reply' } },
  { idempotencyKey: crypto.randomUUID() },
);
const receipt = await client.receipts.getById(result.receiptId);
const checksumValid = await client.receipts.verify(receipt);
```

The API returns a success envelope such as `{ success: true, data, meta? }`; SDK convenience methods unwrap `data`. Errors preserve the HTTP status and Kawnix error details in `KawnixSDKError`.

## SDK namespaces
- `client.providers`: Session control plane: registerEndpoint, updateEndpoint, pauseEndpoint, resumeEndpoint, listEndpoints
- `client.manifests`: Session control plane: validate, publish, listVersions, getVersion, submit, activateVersion, deprecateVersion
- `client.invocations`: API-key data plane: execute, executeStream, getStatus, enqueue, getInvocation, cancel, followEvents
- `client.artifacts`: API-key data plane: createUpload, complete, download, delete
- `client.receipts`: API-key data plane: getById, verify, listByConsumer
- `client.credentials`: Session control plane: createApiKey, listApiKeys, revokeApiKey, rotateApiKey
- `client.billing`: Mixed auth by route: estimateCost, reserve, confirmSettlement, getSettlementStatus
- `client.connectors`: Mixed surface: session-backed list/create plus local registry helpers. Use current OpenAPI paths for remote operations; legacy get/update/remove paths are not contract-backed.
- `client.subscriptions`: Session control plane. Use Consumer Console/current OpenAPI routes: the convenience create/cancel shapes do not yet cover the complete approval lifecycle.
- `client.permissions`: Legacy convenience wrapper; no standalone /api/permissions routes exist in the current OpenAPI contract.
- `client.actions`: Session control plane: list, execute
- `client.workflows`: Session control plane: list, get, create, publish, setStatus, archive, catalog, listRuns, run, getRun, cancelRun, retryRun
- `client.observability`: Session control plane: listEvents, getEvent, metrics
- `client.deadLetters`: Session control plane: list, replay, resolve
- `client.triggers`: In-process trigger utilities; not a hosted persistence substitute.
- `client.operations`: Generated method for every OpenAPI operation ID; authoritative route inventory.

Authentication caveat: the presence of a namespace does not change the route's authentication policy. Management namespaces call session-protected control-plane routes; discovery, invocation, receipts, and protocol billing use scoped API keys. Local connector execution and everything under `client.experimentalLocal` run in the caller process and are not Kawnix-hosted persistence.

## Errors and retries
- 400 or 422: fix the request or contract; do not retry unchanged input.
- 401 or 403: correct authentication, scope, role, subscription, or permission.
- 404: the resource is missing or not visible to the current principal.
- 409: reconcile lifecycle state or idempotency-key reuse.
- 429: back off with jitter and respect server retry guidance.
- 5xx or 503: retry only safe/idempotent operations with bounded backoff.

## Source-of-truth rules for language models
- Prefer the current OpenAPI contract and generated `client.operations` methods over remembered route names.
- Never invent a scope, manifest field, operation ID, or response shape.
- Never put API keys, OAuth tokens, provider secrets, or vault values in client-side code, manifests, logs, or examples.
- Treat exact endpoint IDs, manifest IDs, versions, subscription IDs, workflow versions, and receipt IDs as distinct values.
- Ask for missing required identifiers instead of guessing them.