@intrig/plugin-react 0.0.1

package/src/lib/templates/docs/__snapshots__/download-hook.spec.ts.snap

@@ -0,0 +1,1445 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`reactDownloadHookDocs > handles case-insensitive path parameter detection 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadInvoiceDownload } from "@intrig/react/invoices/{invoiceId}/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadInvoiceResp, downloadInvoice] = useDownloadInvoiceDownload({
+  clearOnUnmount: true,
+});
+// e.g., in a click handler:
+downloadInvoice(downloadInvoiceParams);
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadInvoice } from "@intrig/react/invoices/{invoiceId}/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadInvoiceResp, downloadInvoice] = useDownloadInvoice({
+  clearOnUnmount: true,
+});
+// later:
+downloadInvoice(downloadInvoiceParams);
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadInvoiceDownload } from "@intrig/react/invoices/{invoiceId}/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadInvoiceResp, downloadInvoice] = useDownloadInvoiceDownload({
+    clearOnUnmount: true,
+  });
+
+  return (
+    <button
+      onClick={() => downloadInvoice(downloadInvoiceParams)}
+      disabled={isPending(downloadInvoiceResp)}
+    >
+      {isPending(downloadInvoiceResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { DownloadInvoiceParams } from "@intrig/react/invoices/{invoiceId}/DownloadInvoice.params";
+import type { DownloadInvoiceResponseBody } from "@intrig/react/invoices/{invoiceId}/DownloadInvoice.response";
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadInvoiceDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: DownloadInvoiceParams) => void\`
+
+### \`useDownloadInvoice\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: DownloadInvoiceParams) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadInvoiceResp, downloadInvoice] = useDownloadInvoiceDownload({
+  clearOnUnmount: true,
+});
+
+<button
+  onClick={() => downloadInvoice(downloadInvoiceParams)}
+  disabled={isPending(downloadInvoiceResp)}
+>
+  {isPending(downloadInvoiceResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadInvoiceResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadInvoice(downloadInvoiceParams);
+}, [downloadInvoice]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadInvoiceResp, downloadInvoice] = useDownloadInvoice({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  if (isSuccess(downloadInvoiceResp)) {
+    const ct =
+      downloadInvoiceResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadInvoiceResp.data)
+      ? downloadInvoiceResp.data
+      : [downloadInvoiceResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadInvoiceResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > handles empty variables array 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadBackupDownload } from "@intrig/react/backup/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadBackupResp, downloadBackup] = useDownloadBackupDownload({
+  clearOnUnmount: true,
+});
+// e.g., in a click handler:
+downloadBackup({});
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadBackup } from "@intrig/react/backup/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadBackupResp, downloadBackup] = useDownloadBackup({
+  clearOnUnmount: true,
+});
+// later:
+downloadBackup({});
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadBackupDownload } from "@intrig/react/backup/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadBackupResp, downloadBackup] = useDownloadBackupDownload({
+    clearOnUnmount: true,
+  });
+
+  return (
+    <button
+      onClick={() => downloadBackup({})}
+      disabled={isPending(downloadBackupResp)}
+    >
+      {isPending(downloadBackupResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadBackupDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: Record<string, unknown>) => void\`
+
+### \`useDownloadBackup\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: Record<string, unknown>) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadBackupResp, downloadBackup] = useDownloadBackupDownload({
+  clearOnUnmount: true,
+});
+
+<button
+  onClick={() => downloadBackup({})}
+  disabled={isPending(downloadBackupResp)}
+>
+  {isPending(downloadBackupResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadBackupResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadBackup({});
+}, [downloadBackup]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadBackupResp, downloadBackup] = useDownloadBackup({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  if (isSuccess(downloadBackupResp)) {
+    const ct =
+      downloadBackupResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadBackupResp.data)
+      ? downloadBackupResp.data
+      : [downloadBackupResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadBackupResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > handles multiple path params 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadProjectAssetDownload } from "@intrig/react/projects/{projectId}/assets/{assetId}/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadProjectAssetResp, downloadProjectAsset] =
+  useDownloadProjectAssetDownload({ clearOnUnmount: true });
+// e.g., in a click handler:
+downloadProjectAsset(downloadProjectAssetParams);
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadProjectAsset } from "@intrig/react/projects/{projectId}/assets/{assetId}/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadProjectAssetResp, downloadProjectAsset] =
+  useDownloadProjectAsset({ clearOnUnmount: true });
+// later:
+downloadProjectAsset(downloadProjectAssetParams);
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadProjectAssetDownload } from "@intrig/react/projects/{projectId}/assets/{assetId}/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadProjectAssetResp, downloadProjectAsset] =
+    useDownloadProjectAssetDownload({ clearOnUnmount: true });
+
+  return (
+    <button
+      onClick={() => downloadProjectAsset(downloadProjectAssetParams)}
+      disabled={isPending(downloadProjectAssetResp)}
+    >
+      {isPending(downloadProjectAssetResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { DownloadProjectAssetParams } from "@intrig/react/projects/{projectId}/assets/{assetId}/DownloadProjectAsset.params";
+import type { DownloadProjectAssetResponseBody } from "@intrig/react/projects/{projectId}/assets/{assetId}/DownloadProjectAsset.response";
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadProjectAssetDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: DownloadProjectAssetParams) => void\`
+
+### \`useDownloadProjectAsset\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: DownloadProjectAssetParams) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadProjectAssetResp, downloadProjectAsset] =
+  useDownloadProjectAssetDownload({ clearOnUnmount: true });
+
+<button
+  onClick={() => downloadProjectAsset(downloadProjectAssetParams)}
+  disabled={isPending(downloadProjectAssetResp)}
+>
+  {isPending(downloadProjectAssetResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadProjectAssetResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadProjectAsset(downloadProjectAssetParams);
+}, [downloadProjectAsset]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadProjectAssetResp, downloadProjectAsset] =
+  useDownloadProjectAsset({ clearOnUnmount: true });
+
+useEffect(() => {
+  if (isSuccess(downloadProjectAssetResp)) {
+    const ct =
+      downloadProjectAssetResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadProjectAssetResp.data)
+      ? downloadProjectAssetResp.data
+      : [downloadProjectAssetResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadProjectAssetResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > handles query params mixed with path params 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadTaskFileDownload } from "@intrig/react/tasks/{taskId}/files/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadTaskFileResp, downloadTaskFile] = useDownloadTaskFileDownload({
+  clearOnUnmount: true,
+});
+// e.g., in a click handler:
+downloadTaskFile(downloadTaskFileParams);
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadTaskFile } from "@intrig/react/tasks/{taskId}/files/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadTaskFileResp, downloadTaskFile] = useDownloadTaskFile({
+  clearOnUnmount: true,
+});
+// later:
+downloadTaskFile(downloadTaskFileParams);
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadTaskFileDownload } from "@intrig/react/tasks/{taskId}/files/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadTaskFileResp, downloadTaskFile] = useDownloadTaskFileDownload({
+    clearOnUnmount: true,
+  });
+
+  return (
+    <button
+      onClick={() => downloadTaskFile(downloadTaskFileParams)}
+      disabled={isPending(downloadTaskFileResp)}
+    >
+      {isPending(downloadTaskFileResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { DownloadTaskFileParams } from "@intrig/react/tasks/{taskId}/files/DownloadTaskFile.params";
+import type { DownloadTaskFileResponseBody } from "@intrig/react/tasks/{taskId}/files/DownloadTaskFile.response";
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadTaskFileDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: DownloadTaskFileParams) => void\`
+
+### \`useDownloadTaskFile\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: DownloadTaskFileParams) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadTaskFileResp, downloadTaskFile] = useDownloadTaskFileDownload({
+  clearOnUnmount: true,
+});
+
+<button
+  onClick={() => downloadTaskFile(downloadTaskFileParams)}
+  disabled={isPending(downloadTaskFileResp)}
+>
+  {isPending(downloadTaskFileResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadTaskFileResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadTaskFile(downloadTaskFileParams);
+}, [downloadTaskFile]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadTaskFileResp, downloadTaskFile] = useDownloadTaskFile({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  if (isSuccess(downloadTaskFileResp)) {
+    const ct =
+      downloadTaskFileResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadTaskFileResp.data)
+      ? downloadTaskFileResp.data
+      : [downloadTaskFileResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadTaskFileResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > snapshot — path params only (no request body) 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadFileByIdDownload } from "@intrig/react/files/{id}/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadFileByIdResp, downloadFileById] = useDownloadFileByIdDownload({
+  clearOnUnmount: true,
+});
+// e.g., in a click handler:
+downloadFileById(downloadFileByIdParams);
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadFileById } from "@intrig/react/files/{id}/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadFileByIdResp, downloadFileById] = useDownloadFileById({
+  clearOnUnmount: true,
+});
+// later:
+downloadFileById(downloadFileByIdParams);
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadFileByIdDownload } from "@intrig/react/files/{id}/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadFileByIdResp, downloadFileById] = useDownloadFileByIdDownload({
+    clearOnUnmount: true,
+  });
+
+  return (
+    <button
+      onClick={() => downloadFileById(downloadFileByIdParams)}
+      disabled={isPending(downloadFileByIdResp)}
+    >
+      {isPending(downloadFileByIdResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { DownloadFileByIdParams } from "@intrig/react/files/{id}/DownloadFileById.params";
+import type { DownloadFileByIdResponseBody } from "@intrig/react/files/{id}/DownloadFileById.response";
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadFileByIdDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: DownloadFileByIdParams) => void\`
+
+### \`useDownloadFileById\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: DownloadFileByIdParams) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadFileByIdResp, downloadFileById] = useDownloadFileByIdDownload({
+  clearOnUnmount: true,
+});
+
+<button
+  onClick={() => downloadFileById(downloadFileByIdParams)}
+  disabled={isPending(downloadFileByIdResp)}
+>
+  {isPending(downloadFileByIdResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadFileByIdResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadFileById(downloadFileByIdParams);
+}, [downloadFileById]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadFileByIdResp, downloadFileById] = useDownloadFileById({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  if (isSuccess(downloadFileByIdResp)) {
+    const ct =
+      downloadFileByIdResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadFileByIdResp.data)
+      ? downloadFileByIdResp.data
+      : [downloadFileByIdResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadFileByIdResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > snapshot — request body and path params 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadUserDocumentDownload } from "@intrig/react/users/{userId}/documents/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadUserDocumentResp, downloadUserDocument] =
+  useDownloadUserDocumentDownload({ clearOnUnmount: true });
+// e.g., in a click handler:
+downloadUserDocument(downloadUserDocumentParams);
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadUserDocument } from "@intrig/react/users/{userId}/documents/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadUserDocumentResp, downloadUserDocument] =
+  useDownloadUserDocument({ clearOnUnmount: true });
+// later:
+downloadUserDocument(downloadUserDocumentParams);
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadUserDocumentDownload } from "@intrig/react/users/{userId}/documents/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadUserDocumentResp, downloadUserDocument] =
+    useDownloadUserDocumentDownload({ clearOnUnmount: true });
+
+  return (
+    <button
+      onClick={() => downloadUserDocument(downloadUserDocumentParams)}
+      disabled={isPending(downloadUserDocumentResp)}
+    >
+      {isPending(downloadUserDocumentResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+### Optional types (if generated by your build)
+
+\`\`\`ts
+import type { DownloadUserDocumentParams } from "@intrig/react/users/{userId}/documents/DownloadUserDocument.params";
+import type { DownloadUserDocumentResponseBody } from "@intrig/react/users/{userId}/documents/DownloadUserDocument.response";
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadUserDocumentDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: DownloadUserDocumentParams) => void\`
+
+### \`useDownloadUserDocument\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: DownloadUserDocumentParams) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadUserDocumentResp, downloadUserDocument] =
+  useDownloadUserDocumentDownload({ clearOnUnmount: true });
+
+<button
+  onClick={() => downloadUserDocument(downloadUserDocumentParams)}
+  disabled={isPending(downloadUserDocumentResp)}
+>
+  {isPending(downloadUserDocumentResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadUserDocumentResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadUserDocument(downloadUserDocumentParams);
+}, [downloadUserDocument]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadUserDocumentResp, downloadUserDocument] =
+  useDownloadUserDocument({ clearOnUnmount: true });
+
+useEffect(() => {
+  if (isSuccess(downloadUserDocumentResp)) {
+    const ct =
+      downloadUserDocumentResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadUserDocumentResp.data)
+      ? downloadUserDocumentResp.data
+      : [downloadUserDocumentResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadUserDocumentResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > snapshot — request body only (no path params) 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadCustomReportDownload } from "@intrig/react/reports/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadCustomReportResp, downloadCustomReport] =
+  useDownloadCustomReportDownload({ clearOnUnmount: true });
+// e.g., in a click handler:
+downloadCustomReport({});
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadCustomReport } from "@intrig/react/reports/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadCustomReportResp, downloadCustomReport] =
+  useDownloadCustomReport({ clearOnUnmount: true });
+// later:
+downloadCustomReport({});
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadCustomReportDownload } from "@intrig/react/reports/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadCustomReportResp, downloadCustomReport] =
+    useDownloadCustomReportDownload({ clearOnUnmount: true });
+
+  return (
+    <button
+      onClick={() => downloadCustomReport({})}
+      disabled={isPending(downloadCustomReportResp)}
+    >
+      {isPending(downloadCustomReportResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadCustomReportDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: Record<string, unknown>) => void\`
+
+### \`useDownloadCustomReport\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: Record<string, unknown>) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadCustomReportResp, downloadCustomReport] =
+  useDownloadCustomReportDownload({ clearOnUnmount: true });
+
+<button
+  onClick={() => downloadCustomReport({})}
+  disabled={isPending(downloadCustomReportResp)}
+>
+  {isPending(downloadCustomReportResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadCustomReportResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadCustomReport({});
+}, [downloadCustomReport]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadCustomReportResp, downloadCustomReport] =
+  useDownloadCustomReport({ clearOnUnmount: true });
+
+useEffect(() => {
+  if (isSuccess(downloadCustomReportResp)) {
+    const ct =
+      downloadCustomReportResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadCustomReportResp.data)
+      ? downloadCustomReportResp.data
+      : [downloadCustomReportResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadCustomReportResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;
+
+exports[`reactDownloadHookDocs > snapshot — simple REST descriptor (no body, no path params) 1`] = `
+"# Intrig Download Hooks — Quick Guide
+
+## Copy-paste starter (fast lane)
+
+### Auto-download (most common)
+
+\`\`\`ts
+import { useDownloadReportDownload } from "@intrig/react/reports/client";
+\`\`\`
+
+\`\`\`ts
+import { isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadReportResp, downloadReport] = useDownloadReportDownload({
+  clearOnUnmount: true,
+});
+// e.g., in a click handler:
+downloadReport({});
+\`\`\`
+
+### Manual/stateful (you handle the blob/UI)
+
+\`\`\`ts
+import { useDownloadReport } from "@intrig/react/reports/client";
+\`\`\`
+
+\`\`\`ts
+import { isSuccess, isPending, isError } from "@intrig/react";
+\`\`\`
+
+\`\`\`tsx
+const [downloadReportResp, downloadReport] = useDownloadReport({
+  clearOnUnmount: true,
+});
+// later:
+downloadReport({});
+\`\`\`
+
+---
+
+## TL;DR (auto-download)
+
+\`\`\`tsx
+import { useDownloadReportDownload } from "@intrig/react/reports/client";
+import { isPending, isError } from "@intrig/react";
+
+export default function Example() {
+  const [downloadReportResp, downloadReport] = useDownloadReportDownload({
+    clearOnUnmount: true,
+  });
+
+  return (
+    <button
+      onClick={() => downloadReport({})}
+      disabled={isPending(downloadReportResp)}
+    >
+      {isPending(downloadReportResp) ? "Downloading…" : "Download"}
+    </button>
+  );
+}
+\`\`\`
+
+---
+
+## Hook APIs
+
+### \`useDownloadReportDownload\` (auto-download)
+
+- **What it does:** requests the file with \`responseType: 'blob'\` + \`adapter: 'fetch'\`, derives filename from \`Content-Disposition\` if present, creates a temporary object URL, clicks a hidden \`<a>\`, **downloads**, then resets state to \`init\`.
+- **Signature:** \`[state, download, clear]\`
+  - \`download(params: Record<string, unknown>) => void\`
+
+### \`useDownloadReport\` (manual/stateful)
+
+- **What it does:** same request but **does not** auto-save. You control preview/saving using \`state.data\` + \`state.headers\`.
+- **Signature:** \`[state, fetchFile, clear]\`
+  - \`fetchFile(params: Record<string, unknown>) => void\`
+
+---
+
+## Usage Patterns
+
+### 1) Auto-download on click (recommended)
+
+\`\`\`tsx
+const [downloadReportResp, downloadReport] = useDownloadReportDownload({
+  clearOnUnmount: true,
+});
+
+<button
+  onClick={() => downloadReport({})}
+  disabled={isPending(downloadReportResp)}
+>
+  {isPending(downloadReportResp) ? "Downloading…" : "Download file"}
+</button>;
+{
+  isError(downloadReportResp) ? (
+    <p className="text-red-500">Failed to download.</p>
+  ) : null;
+}
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Most users just need a button that saves the file. This variant handles object URL creation, filename extraction, click, and state reset.</p>
+</details>
+
+### 2) Auto-download on mount (e.g., “Your file is ready” page)
+
+\`\`\`tsx
+useEffect(() => {
+  downloadReport({});
+}, [downloadReport]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Good for post-processing routes that immediately start a download.</p>
+</details>
+
+### 3) Manual handling (preview or custom filename)
+
+\`\`\`tsx
+const [downloadReportResp, downloadReport] = useDownloadReport({
+  clearOnUnmount: true,
+});
+
+useEffect(() => {
+  if (isSuccess(downloadReportResp)) {
+    const ct =
+      downloadReportResp.headers?.["content-type"] ??
+      "application/octet-stream";
+    const parts = Array.isArray(downloadReportResp.data)
+      ? downloadReportResp.data
+      : [downloadReportResp.data];
+    const url = URL.createObjectURL(new Blob(parts, { type: ct }));
+    // preview/save with your own UI...
+    return () => URL.revokeObjectURL(url);
+  }
+}, [downloadReportResp]);
+\`\`\`
+
+<details><summary>Description</summary>
+<p>Use when you need to inspect headers, show a preview, or control the filename/UI flow.</p>
+</details>
+
+---
+
+## Behavior notes (what the auto-download variant does)
+
+- Forces \`responseType: 'blob'\` and \`adapter: 'fetch'\`.
+- If \`content-type\` is JSON, stringifies payload so the saved file is human-readable.
+- Parses \`Content-Disposition\` to derive a filename; falls back to a default.
+- Creates and clicks a temporary link, then **resets state to \`init\`**.
+
+---
+
+## Gotchas & Tips
+
+- **Expose headers in CORS:** server should send  
+  \`Access-Control-Expose-Headers: Content-Disposition, Content-Type\`
+- **Disable double clicks:** guard with \`isPending(state)\`.
+- **Revoke URLs** when you create them manually in the stateful variant.
+- **iOS Safari:** blob downloads may open a new tab—consider server-side direct-download URLs for a smoother UX.
+
+---
+
+## Troubleshooting
+
+- **No filename shown:** your server didn’t include \`Content-Disposition\`. Add it.
+- **Got JSON instead of a file:** server returned \`application/json\` (maybe an error). The auto hook saves it as text; surface the error in UI.
+- **Nothing happens on click:** ensure you’re using the **Download** variant and the request succeeds (check Network tab); verify CORS headers.
+
+---
+"
+`;