docs: async polling guide and SDK 0.6.0 examples

[jonathanpopham]

Summary

• Adds new Async Polling page explaining the job-based API model (statuses, envelope shape, polling mechanism, SDK usage)
• Updates Quickstart to show HTTP 202 responses and the polling pattern instead of the old synchronous response
• Updates Authentication to explain the idempotency key's role in job identity and polling
• Updates Concepts to note all graph generation is asynchronous
• Includes SupermodelClient SDK examples with configurable polling behavior

Test plan

• Verify Mint docs build locally (npx mintlify dev)
• Check all internal links resolve (/async-polling, /api-reference/...)
• Confirm mermaid sequence diagram renders
• Review SDK code examples against @supermodeltools/sdk@0.6.0 API surface

Closes supermodeltools/supermodel-public-api#336

Summary by CodeRabbit

• New Features

  • Graph generation now operates asynchronously: submit jobs and poll for results (202/pending + eventual result).

• Documentation

  • Added a comprehensive async polling guide with examples, lifecycle, error handling, and SDK guidance.
  • Updated Quickstart to show job submission, polling flow, async responses, and nested result.graph.
  • Expanded authentication docs to describe Idempotency-Key purposes: job identity, polling, and request tracing.
  • Added async polling to site navigation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Adds an async polling guide and updates docs to reflect asynchronous graph generation: submit with Idempotency-Key, receive 202 with jobId/retryAfter, poll by re-submitting the same key, and unified response envelope; navigation and concept texts updated; no public APIs changed. (≈40 words)

Changes

Cohort / File(s)	Summary
New Async Polling Documentation async-polling.mdx	New guide describing async processing, unified response envelope (status, jobId, retryAfter, result, error), job lifecycle, polling examples (cURL + SDK), idempotency-key semantics, timeouts, retries, cancellation, and operational notes.
Quickstart flow quickstart.mdx	Reworked flow: Step 2 → "Submit a graph generation job"; introduces generating/storing an Idempotency-Key, 202 Accepted responses with jobId/retryAfter, polling by re-submitting the same key, and nesting successful graph at result.graph.
Authentication / Idempotency docs authentication.mdx	Expanded Idempotency-Key purposes to three items: Job identity, Polling, and Request tracing; clarifies that re-submitting the same key returns existing job/status for polling.
Concepts guidance concepts.mdx	Added a short note that graph generation is asynchronous and users should poll for results.
Navigation docs.json	Added async-polling to Documentation > Overview pages array for navigation.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Client as Client
  participant API as API Server
  participant Queue as Job Queue
  participant Worker as Worker
  participant Store as Result Store

  Client->>API: POST /graphs (Idempotency-Key)
  API-->>Client: 202 Accepted (jobId, retryAfter)
  API->>Queue: enqueue(jobId, payload)
  Note over Queue,Worker: asynchronous processing
  Worker->>Store: write result (jobId -> result)
  Worker-->>Queue: mark job done
  Client->>API: POST /graphs (same Idempotency-Key) — poll
  API->>Store: fetch(jobId)
  alt result available
    API-->>Client: 200 OK (status: succeeded, result)
  else still processing
    API-->>Client: 202 Accepted (status: pending, retryAfter)
  end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• docs: async polling guide and SDK 0.6.0 examples #3 — Mirrors these documentation changes (adds async-polling.mdx and updates quickstart, authentication, concepts, and docs.json).

Poem

Async jobs hum beneath the hood,
Idempotency keeps the state understood.
Poll the same key, wait your turn,
Retry after, watch results return.
Graphs arrive — no chaos, just code. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: adding async polling documentation and updating examples for SDK 0.6.0.
Linked Issues check	✅ Passed	All requirements from issue #336 are met: docs explain SDK polling configuration, show new response shapes, demonstrate HTTP 202 + polling in Quickstart, explain idempotency-key role, and provide SDK examples.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the linked issue objective; no unrelated modifications detected beyond documentation updates and navigation additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@async-polling.mdx`:
- Around line 116-126: The example config has two issues: the timeoutMs value
(600000) is inconsistent with the "5 minutes" comment and the AbortController is
missing; update timeoutMs to 300000 (or change the comment to "10 minutes") and
add a controller instance before creating the SupermodelClient (e.g., create an
AbortController and pass controller.signal into the client) so the referenced
controller.signal is defined and can be used to cancel polling (call
controller.abort() where appropriate); adjust comments accordingly.

🧹 Nitpick comments (2)

async-polling.mdx (1)

93-112: Heads up on Blob in Node.js.

The Blob constructor exists natively in Node.js 18+, but if users are on an older version or using CommonJS, they might hit issues. Might be worth a quick note or showing the alternative:

// Node.js 18+ (native Blob)
const file = new Blob([zipBuffer], { type: 'application/zip' });

// Older Node.js versions
// const { Blob } = require('buffer');

Not a blocker — just something that could save a support ticket or two.

quickstart.mdx (1)

53-65: Quick clarification might help here.

The polling requires re-uploading the zip file each time, which might surprise users coming from APIs where you poll a /jobs/{id} endpoint. Maybe add a small note explaining why?

Something like:

"Yes, you re-submit the file — the server uses your Idempotency-Key to find the existing job and won't re-process it."

Not a blocker, just might prevent some "wait, really?" moments.

[jonathanpopham]

Integration Test Results - All Endpoints

Tested all 5 graph endpoints against production API following the documented async polling pattern.

Test fixture: 4-file TypeScript project (main.ts, utils.ts, logger.ts, validator.ts) with imports, classes, and an intentionally dead function (unusedHelper).

Flow Verified

All endpoints follow the documented pattern exactly:

1. Submit → HTTP 202, {status: "pending", jobId: "<idempotency-key>", retryAfter: 10}
2. Poll (same request, same key) → HTTP 200, {status: "completed", result: {...}}

Results by Endpoint

Endpoint	Status	Nodes	Relationships	Notes
/v1/graphs/dependency	completed	16	16	Files, Classes, Functions, LocalDependency nodes. IMPORTS, CONTAINS_FILE, DEFINES_FUNCTION, DECLARES_CLASS edges
/v1/graphs/call	completed	4	3	Only called functions appear (main, processItems, info, validate). unusedHelper/warn/error correctly absent
/v1/graphs/domain	completed	4 domains	4 relationships	Domains: Orchestration, DataTransforms, Validation, Observability. Includes subdomains, function descriptions
/v1/graphs/parse	completed	16	16	Full AST-level structure matching dependency graph
/v1/graphs/supermodel	completed	16	3 (call edges)	Unified graph with summary: 7 functions, 1 class, 4 domains, 4 files

Response Envelope (actual)

Initial submission (all 5 returned this shape):

{
  "status": "pending",
  "jobId": "docs-test-dep-9C8C3CBC-9E99-4BE5-B9BC-36C06BE15772",
  "retryAfter": 10,
  "error": null,
  "result": null
}

After polling (example from dependency graph):

{
  "status": "completed",
  "jobId": "docs-test-dep-9C8C3CBC-9E99-4BE5-B9BC-36C06BE15772",
  "retryAfter": null,
  "error": null,
  "result": {
    "generatedAt": "2026-01-24T18:11:27.032Z",
    "message": "dependency graph generated successfully",
    "stats": null,
    "graph": {
      "nodes": [...],
      "relationships": [...]
    }
  }
}

Documentation Accuracy Notes

1. Docs show retryAfter: 5 in examples — production returns retryAfter: 10. The docs are fine since the value is server-provided and the docs just show it as illustrative.
2. Docs show initial status as "processing" — production returns "pending" initially. Both are valid intermediate states per the docs. Updated the quickstart example to use "pending" for accuracy.
3. Completed responses include "error": null and "retryAfter": null — not just absent fields. Docs should reflect this.
4. The jobId matches the Idempotency-Key exactly — this is consistent with the documented behavior.

All 5 endpoints are functional and match the documented contract.