{
  "slug": "sdk/protocol",
  "title": "Protocol overview",
  "description": "How the wire protocol, SDKs, and ingest endpoint fit together.",
  "url": "https://cuitty.com/docs/sdk/protocol",
  "markdown_url": "https://cuitty.com/docs/sdk/protocol.md",
  "json_url": "https://cuitty.com/docs/sdk/protocol.json",
  "frontmatter": {
    "title": "Protocol overview",
    "description": "How the wire protocol, SDKs, and ingest endpoint fit together.",
    "order": 7,
    "section": "SDK",
    "updatedAt": "2026-04-27"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "protocol-overview",
      "text": "Protocol overview"
    },
    {
      "depth": 2,
      "slug": "three-things-the-sdk-gives-you",
      "text": "Three things the SDK gives you"
    },
    {
      "depth": 2,
      "slug": "three-things-the-sdk-does-not-do",
      "text": "Three things the SDK does not do"
    },
    {
      "depth": 2,
      "slug": "the-contract",
      "text": "The contract"
    }
  ],
  "body_markdown": "# Protocol overview\n\nThe SDK is a convenience layer. Everything underneath is a single HTTP endpoint accepting a batch of typed events.\n\n```\n                     ┌───────────────────┐\n   Application ───►  │   @cuitty/sdk     │  ─── HMAC-signed POST ───►  Portal\n                     │  (or curl, etc.)   │\n                     └───────────────────┘\n```\n\n## Three things the SDK gives you\n\n1. **Batching.** Events accumulate in memory and flush every 5 seconds, or on buffer fill, or on `shutdown()`.\n2. **Signing.** HMAC-SHA256 over the body using your API key — no need to hand-roll OpenSSL.\n3. **Plugins.** Tap into framework middleware, Pino, or your CI pipeline without rewriting your app.\n\n## Three things the SDK does *not* do\n\n- Poll Cuitty for data — the SDK is push-only.\n- Retry indefinitely — failed batches drop after `maxRetries` and are logged locally.\n- Throw exceptions on transport errors — fail-silent is a deliberate design choice; SDK errors must never crash the host process.\n\n## The contract\n\nThe contract between SDK and portal is documented in full at [Wire protocol](/docs/reference/wire-protocol). Anything that conforms to the contract works — implement your own client in any language.",
  "links_out": [
    "/docs/reference/wire-protocol"
  ]
}