{
  "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.",
  "body_html": "<h1 id=\"protocol-overview\">Protocol overview</h1>\n<p>The SDK is a convenience layer. Everything underneath is a single HTTP endpoint accepting a batch of typed events.</p>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"plaintext\"><code><span class=\"line\"><span>                     ┌───────────────────┐</span></span>\n<span class=\"line\"><span>   Application ───►  │   @cuitty/sdk     │  ─── HMAC-signed POST ───►  Portal</span></span>\n<span class=\"line\"><span>                     │  (or curl, etc.)   │</span></span>\n<span class=\"line\"><span>                     └───────────────────┘</span></span></code></pre>\n<h2 id=\"three-things-the-sdk-gives-you\">Three things the SDK gives you</h2>\n<ol>\n<li><strong>Batching.</strong> Events accumulate in memory and flush every 5 seconds, or on buffer fill, or on <code>shutdown()</code>.</li>\n<li><strong>Signing.</strong> HMAC-SHA256 over the body using your API key — no need to hand-roll OpenSSL.</li>\n<li><strong>Plugins.</strong> Tap into framework middleware, Pino, or your CI pipeline without rewriting your app.</li>\n</ol>\n<h2 id=\"three-things-the-sdk-does-not-do\">Three things the SDK does <em>not</em> do</h2>\n<ul>\n<li>Poll Cuitty for data — the SDK is push-only.</li>\n<li>Retry indefinitely — failed batches drop after <code>maxRetries</code> and are logged locally.</li>\n<li>Throw exceptions on transport errors — fail-silent is a deliberate design choice; SDK errors must never crash the host process.</li>\n</ul>\n<h2 id=\"the-contract\">The contract</h2>\n<p>The contract between SDK and portal is documented in full at <a href=\"/docs/reference/wire-protocol\">Wire protocol</a>. Anything that conforms to the contract works — implement your own client in any language.</p>",
  "links_out": [
    "/docs/reference/wire-protocol"
  ]
}