nuxt-openapi-hyperfetch 0.3.0-beta → 0.3.1-beta

package/src/generators/components/connector-generator/templates.ts

@@ -15,7 +15,6 @@ function generateFileHeader(): string {
  */
 
 /* eslint-disable */
-// @ts-nocheck
 `;
 }
 
@@ -42,18 +41,37 @@ function toFileName(composableName: string): string {
 /**
  * Build all `import` lines for a resource connector.
  */
-function buildImports(resource: ResourceInfo, composablesRelDir: string): string {
+function buildImports(resource: ResourceInfo, composablesRelDir: string, sdkRelDir: string): string {
   const lines: string[] = [];
 
   // zod
   lines.push(`import { z } from 'zod';`);
   lines.push('');
 
-  // runtime helpers (Nuxt alias — set up by the Nuxt module)
-  const runtimeHelpers: string[] = [];
+  // connector-types — structural interfaces for return types
+  const connectorTypeImports: string[] = ['ListConnectorReturn'];
+  if (resource.detailEndpoint) {
+    connectorTypeImports.push('DetailConnectorReturn');
+  }
+  if (resource.createEndpoint || resource.updateEndpoint) {
+    connectorTypeImports.push('FormConnectorReturn');
+  }
+  if (resource.deleteEndpoint) {
+    connectorTypeImports.push('DeleteConnectorReturn');
+  }
+  lines.push(`import type { ${connectorTypeImports.join(', ')} } from '#nxh/runtime/connector-types';`);
+  lines.push('');
+
+  // SDK request/response types (for the params overload signature)
   if (resource.listEndpoint) {
-    runtimeHelpers.push('useListConnector');
+    const requestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+    lines.push(`import type { ${requestTypeName} } from '${sdkRelDir}';`);
+    lines.push('');
   }
+
+  // runtime helpers (Nuxt alias — set up by the Nuxt module)
+  // useListConnector is always imported to support the optional factory pattern
+  const runtimeHelpers: string[] = ['useListConnector'];
   if (resource.detailEndpoint) {
     runtimeHelpers.push('useDetailConnector');
   }
@@ -141,6 +159,68 @@ function buildColumns(resource: ResourceInfo): string {
   return `const ${varName} = [\n${entries},\n];`;
 }
 
+/**
+ * Build the TypeScript options interface for a connector.
+ * Only includes fields relevant to the endpoints present on the resource.
+ */
+function buildOptionsInterface(resource: ResourceInfo): string {
+  const typeName = `${pascalCase(resource.composableName)}Options`;
+  const hasColumns = resource.columns && resource.columns.length > 0;
+  const fields: string[] = [];
+
+  if (resource.listEndpoint && hasColumns) {
+    fields.push(`  columnLabels?: Record<string, string>;`);
+    fields.push(`  columnLabel?: (key: string) => string;`);
+  }
+  if (resource.createEndpoint && resource.zodSchemas.create) {
+    fields.push(`  createSchema?: z.ZodTypeAny | ((base: z.ZodTypeAny) => z.ZodTypeAny);`);
+  }
+  if (resource.updateEndpoint && resource.zodSchemas.update) {
+    fields.push(`  updateSchema?: z.ZodTypeAny | ((base: z.ZodTypeAny) => z.ZodTypeAny);`);
+  }
+
+  if (fields.length === 0) {
+    return `type ${typeName} = Record<string, never>;`;
+  }
+
+  return [`interface ${typeName} {`, ...fields, `}`].join('\n');
+}
+
+/**
+ * Build the TypeScript return type for a connector.
+ */
+function buildReturnType(resource: ResourceInfo): string {
+  const pascal = pascalCase(resource.name);
+  const typeName = `${pascalCase(resource.composableName)}Return`;
+  const fields: string[] = [];
+
+  // table is always present in the return type:
+  //   - if listEndpoint exists → ListConnectorReturn<T> (always defined)
+  //   - if no listEndpoint      → ListConnectorReturn<unknown> | undefined (only when factory passed)
+  if (resource.listEndpoint) {
+    fields.push(`  table: ListConnectorReturn<${pascal}>;`);
+  } else {
+    fields.push(`  table: ListConnectorReturn<unknown> | undefined;`);
+  }
+
+  if (resource.detailEndpoint) {
+    fields.push(`  detail: DetailConnectorReturn<${pascal}>;`);
+  }
+  if (resource.createEndpoint) {
+    const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
+    fields.push(`  createForm: FormConnectorReturn<${inputType}>;`);
+  }
+  if (resource.updateEndpoint) {
+    const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
+    fields.push(`  updateForm: FormConnectorReturn<${inputType}>;`);
+  }
+  if (resource.deleteEndpoint) {
+    fields.push(`  deleteAction: DeleteConnectorReturn<${pascal}>;`);
+  }
+
+  return [`type ${typeName} = {`, ...fields, `};`].join('\n');
+}
+
 /**
  * Build the body of the exported connector function.
  */
@@ -154,6 +234,10 @@ function buildFunctionBody(resource: ResourceInfo): string {
   const columnsVar = `${camel}Columns`;
   const subConnectors: string[] = [];
 
+  // Derived type names — must match buildOptionsInterface / buildReturnType
+  const optionsTypeName = `${pascalCase(resource.composableName)}Options`;
+  const returnTypeName = `${pascalCase(resource.composableName)}Return`;
+
   // Destructure options param — only what's relevant for this resource
   const optionKeys: string[] = [];
   if (resource.listEndpoint && hasColumns) {
@@ -169,67 +253,71 @@ function buildFunctionBody(resource: ResourceInfo): string {
   const optionsDestructure =
     optionKeys.length > 0 ? `  const { ${optionKeys.join(', ')} } = options;\n` : '';
 
+  // ── List / table sub-connector ─────────────────────────────────────────────
   if (resource.listEndpoint) {
     const fn = toAsyncDataName(resource.listEndpoint.operationId);
-    // paginated: true tells useListConnector to expose pagination helpers
-    // (goToPage, nextPage, prevPage, setPerPage, pagination ref).
-    // We set it whenever the spec declares a list endpoint that has a response schema,
-    // which is a reliable proxy for "this API returns structured data worth paginating".
+    const listRequestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
     const paginatedFlag = resource.listEndpoint.responseSchema ? 'paginated: true' : '';
     const columnsArg = hasColumns ? `columns: ${columnsVar}` : '';
     const labelArgs = hasColumns ? 'columnLabels, columnLabel' : '';
     const allArgs = [paginatedFlag, columnsArg, labelArgs].filter(Boolean).join(', ');
     const opts = allArgs ? `{ ${allArgs} }` : '{}';
-    subConnectors.push(`  const table = useListConnector(${fn}, ${opts});`);
+
+    // Factory: if the first arg is a function the user provided their own composable;
+    // otherwise build a default factory from the plain params object.
+    subConnectors.push(
+      `  const isFactory = typeof paramsOrSource === 'function';`,
+      `  const listFactory = isFactory`,
+      `    ? (paramsOrSource as () => unknown)`,
+      `    : () => ${fn}((paramsOrSource ?? {}) as ${listRequestTypeName});`,
+      `  const table = useListConnector(listFactory, ${opts}) as unknown as ListConnectorReturn<${pascal}>;`
+    );
+  } else {
+    // No list endpoint — support optional factory for developer-provided list
+    subConnectors.push(
+      `  const table = paramsOrSource`,
+      `    ? (useListConnector(paramsOrSource as () => unknown, {}) as unknown as ListConnectorReturn<unknown>)`,
+      `    : undefined;`
+    );
   }
 
   if (resource.detailEndpoint) {
     const fn = toAsyncDataName(resource.detailEndpoint.operationId);
-    subConnectors.push(`  const detail = useDetailConnector(${fn});`);
+    subConnectors.push(`  const detail = useDetailConnector(${fn}) as unknown as DetailConnectorReturn<${pascal}>;`);
   }
 
   if (resource.createEndpoint) {
     const fn = toAsyncDataName(resource.createEndpoint.operationId);
+    const inputType = resource.zodSchemas.create ? `${pascal}CreateInput` : `Record<string, unknown>`;
     const schemaArg = resource.zodSchemas.create
       ? `{ schema: ${pascal}CreateSchema, schemaOverride: createSchema }`
       : '{}';
-    subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg});`);
+    subConnectors.push(`  const createForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
   }
 
   if (resource.updateEndpoint) {
     const fn = toAsyncDataName(resource.updateEndpoint.operationId);
     const hasDetail = !!resource.detailEndpoint;
+    const inputType = resource.zodSchemas.update ? `${pascal}UpdateInput` : `Record<string, unknown>`;
 
-    // Build the options argument for useFormConnector:
-    //   schema      → Zod schema for client-side validation before submission
-    //   loadWith    → reference to the detail connector so the form auto-fills
-    //                 when detail.item changes (user clicks "Edit" on a row)
-    //
-    // Four combinations are possible depending on what the spec provides:
     let schemaArg = '{}';
     if (resource.zodSchemas.update && hasDetail) {
-      // Best case: validate AND pre-fill from detail
       schemaArg = `{ schema: ${pascal}UpdateSchema, schemaOverride: updateSchema, loadWith: detail }`;
     } else if (resource.zodSchemas.update) {
-      // Validate, but no detail endpoint to pre-fill from
       schemaArg = `{ schema: ${pascal}UpdateSchema, schemaOverride: updateSchema }`;
     } else if (hasDetail) {
-      // No Zod schema (no request body in spec), but still pre-fill from detail
       schemaArg = `{ loadWith: detail }`;
     }
-    subConnectors.push(`  const updateForm = useFormConnector(${fn}, ${schemaArg});`);
+    subConnectors.push(`  const updateForm = useFormConnector(${fn}, ${schemaArg}) as unknown as FormConnectorReturn<${inputType}>;`);
   }
 
   if (resource.deleteEndpoint) {
     const fn = toAsyncDataName(resource.deleteEndpoint.operationId);
-    subConnectors.push(`  const deleteAction = useDeleteConnector(${fn});`);
+    subConnectors.push(`  const deleteAction = useDeleteConnector(${fn}) as unknown as DeleteConnectorReturn<${pascal}>;`);
   }
 
-  // Return object — only include what was built
-  const returnKeys: string[] = [];
-  if (resource.listEndpoint) {
-    returnKeys.push('table');
-  }
+  // Return object — always includes table (undefined when no list + no factory)
+  const returnKeys: string[] = ['table'];
   if (resource.detailEndpoint) {
     returnKeys.push('detail');
   }
@@ -243,17 +331,36 @@ function buildFunctionBody(resource: ResourceInfo): string {
     returnKeys.push('deleteAction');
   }
 
-  const returnStatement = `  return { ${returnKeys.join(', ')} };`;
+  const returnStatement = `  return { ${returnKeys.join(', ')} } as ${returnTypeName};`;
 
-  return [
-    `export function ${resource.composableName}(options = {}) {`,
-    optionsDestructure.trimEnd(),
-    ...subConnectors,
-    returnStatement,
-    `}`,
-  ]
-    .filter((s) => s !== '')
-    .join('\n');
+  // ── Function signature ─────────────────────────────────────────────────────
+  // Resources WITH a list endpoint: two overloads (factory | params).
+  // Resources WITHOUT a list endpoint: single signature with optional factory.
+  const lines: string[] = [];
+
+  if (resource.listEndpoint) {
+    const listRequestTypeName = `${pascalCase(resource.listEndpoint.operationId)}Request`;
+    lines.push(
+      `export function ${resource.composableName}(source: () => unknown, options?: ${optionsTypeName}): ${returnTypeName};`,
+      `export function ${resource.composableName}(params?: ${listRequestTypeName}, options?: ${optionsTypeName}): ${returnTypeName};`,
+      `export function ${resource.composableName}(paramsOrSource?: ${listRequestTypeName} | (() => unknown), options: ${optionsTypeName} = {}): ${returnTypeName} {`
+    );
+  } else {
+    lines.push(
+      `export function ${resource.composableName}(source?: () => unknown, options: ${optionsTypeName} = {}): ${returnTypeName} {`
+    );
+    // Alias so the body can use paramsOrSource uniformly
+    lines.push(`  const paramsOrSource = source;`);
+  }
+
+  if (optionsDestructure.trim()) {
+    lines.push(optionsDestructure.trimEnd());
+  }
+  lines.push(...subConnectors);
+  lines.push(returnStatement);
+  lines.push(`}`);
+
+  return lines.join('\n');
 }
 
 // ─── Public API ───────────────────────────────────────────────────────────────
@@ -265,16 +372,21 @@ function buildFunctionBody(resource: ResourceInfo): string {
  * @param composablesRelDir  Relative path from the connector dir to the
  *                           useAsyncData composables dir (e.g. '../use-async-data')
  */
-export function generateConnectorFile(resource: ResourceInfo, composablesRelDir: string): string {
+export function generateConnectorFile(
+  resource: ResourceInfo,
+  composablesRelDir: string,
+  sdkRelDir = '../..'
+): string {
   const header = generateFileHeader();
-  const imports = buildImports(resource, composablesRelDir);
+  const imports = buildImports(resource, composablesRelDir, sdkRelDir);
   const schemas = buildZodSchemas(resource);
   const columns = buildColumns(resource);
+  const optionsInterface = buildOptionsInterface(resource);
+  const returnType = buildReturnType(resource);
   const fn = buildFunctionBody(resource);
 
-  // Assemble file: header + imports + (optional) Zod blocks + columns const + function body.
-  // Each section ends with its own trailing newline; join with \n adds one blank
-  // line between sections, which matches Prettier's output for this structure.
+  // Assemble file: header + imports + (optional) Zod blocks + columns const +
+  // options interface + return type + function body.
   const parts: string[] = [header, imports];
   if (schemas.trim()) {
     parts.push(schemas);
@@ -282,6 +394,8 @@ export function generateConnectorFile(resource: ResourceInfo, composablesRelDir:
   if (columns.trim()) {
     parts.push(columns);
   }
+  parts.push(optionsInterface);
+  parts.push(returnType);
   parts.push(fn);
 
   return parts.join('\n') + '\n';

package/src/generators/shared/runtime/connector-types.ts

@@ -0,0 +1,142 @@
+/**
+ * connector-types.ts — Structural return type interfaces for the 4 runtime connectors.
+ *
+ * Uses locally-defined minimal type aliases for Ref/ComputedRef/ShallowRef so this
+ * file compiles in the CLI context (where Vue is not installed) and remains
+ * structurally compatible with Vue's actual types in the user's Nuxt project.
+ *
+ * Copied to the user's project alongside the generated connectors and runtime helpers.
+ */
+
+// Minimal structural aliases — compatible with Vue's Ref<T>, ComputedRef<T>, ShallowRef<T>.
+// These are intentionally kept as simple as possible to avoid coupling to Vue's internals.
+type Ref<T> = { value: T };
+type ShallowRef<T> = { value: T };
+type ComputedRef<T> = { readonly value: T };
+
+// ─── Column / field defs (mirrors schema-analyzer output) ────────────────────
+
+export interface ColumnDef {
+  key: string;
+  label: string;
+  type: string;
+}
+
+export interface FormFieldDef {
+  key: string;
+  label: string;
+  type: string;
+  required: boolean;
+  options?: { label: string; value: string }[];
+  placeholder?: string;
+  hidden?: boolean;
+}
+
+// ─── Pagination ───────────────────────────────────────────────────────────────
+
+export interface PaginationState {
+  page: number;
+  perPage: number;
+  total: number;
+  totalPages: number;
+  goToPage: (page: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  setPerPage: (n: number) => void;
+}
+
+// ─── ListConnectorReturn ──────────────────────────────────────────────────────
+
+export interface ListConnectorReturn<TRow = unknown> {
+  // State
+  rows: ComputedRef<TRow[]>;
+  columns: ComputedRef<ColumnDef[]>;
+  loading: ComputedRef<boolean>;
+  error: ComputedRef<unknown>;
+
+  // Pagination
+  pagination: ComputedRef<PaginationState | null>;
+  goToPage: (page: number) => void;
+  nextPage: () => void;
+  prevPage: () => void;
+  setPerPage: (n: number) => void;
+
+  // Selection
+  selected: Ref<TRow[]>;
+  onRowSelect: (row: TRow) => void;
+  clearSelection: () => void;
+
+  // Actions
+  refresh: () => void;
+
+  // CRUD coordination — public methods
+  create: () => void;
+  update: (row: TRow) => void;
+  remove: (row: TRow) => void;
+
+  // CRUD coordination — internal triggers (watch in the parent component)
+  _createTrigger: Ref<number>;
+  _updateTarget: ShallowRef<TRow | null>;
+  _deleteTarget: ShallowRef<TRow | null>;
+}
+
+// ─── DetailConnectorReturn ────────────────────────────────────────────────────
+
+export interface DetailConnectorReturn<TItem = unknown> {
+  // State
+  item: ComputedRef<TItem | null>;
+  loading: ComputedRef<boolean>;
+  error: ComputedRef<unknown>;
+  fields: ComputedRef<FormFieldDef[]>;
+
+  // Actions
+  load: (id: string | number) => Promise<void>;
+  clear: () => void;
+
+  // Internals (advanced use)
+  _composable: unknown;
+  _currentId: Ref<string | number | null>;
+}
+
+// ─── FormConnectorReturn ──────────────────────────────────────────────────────
+
+export interface FormConnectorReturn<TInput = Record<string, unknown>> {
+  // State
+  model: Ref<Partial<TInput>>;
+  errors: Ref<Record<string, string[]>>;
+  loading: Ref<boolean>;
+  submitError: Ref<unknown>;
+  submitted: Ref<boolean>;
+  isValid: ComputedRef<boolean>;
+  hasErrors: ComputedRef<boolean>;
+  fields: ComputedRef<FormFieldDef[]>;
+
+  // Callbacks (developer-assignable)
+  onSuccess: Ref<((data: unknown) => void) | null>;
+  onError: Ref<((err: unknown) => void) | null>;
+
+  // Actions
+  submit: () => Promise<void>;
+  reset: () => void;
+  setValues: (data: Partial<TInput>) => void;
+}
+
+// ─── DeleteConnectorReturn ────────────────────────────────────────────────────
+
+export interface DeleteConnectorReturn<TItem = unknown> {
+  // State
+  target: Ref<TItem | null>;
+  isOpen: Ref<boolean>;
+  loading: Ref<boolean>;
+  error: Ref<unknown>;
+  hasTarget: ComputedRef<boolean>;
+
+  // Callbacks (developer-assignable)
+  onSuccess: Ref<((item: TItem) => void) | null>;
+  onError: Ref<((err: unknown) => void) | null>;
+
+  // Actions
+  setTarget: (item: TItem) => void;
+  cancel: () => void;
+  confirm: () => Promise<void>;
+}

package/src/generators/shared/runtime/useListConnector.ts

@@ -13,14 +13,16 @@
 import { ref, computed, shallowRef } from 'vue';
 
 /**
- * @param composableFn  The generated useAsyncData composable, e.g. useAsyncDataGetPets
- * @param options       Configuration for the list connector
+ * @param factory   A zero-argument function that calls and returns the underlying
+ *                  useAsyncData composable, e.g. () => useAsyncDataGetPets(params)
+ *                  The factory is called once during connector setup (inside setup()).
+ * @param options   Configuration for the list connector
  */
-export function useListConnector(composableFn, options = {}) {
+export function useListConnector(factory, options = {}) {
   const { paginated = false, columns = [], columnLabels = {}, columnLabel = null } = options;
 
   // ── Execute the underlying composable ──────────────────────────────────────
-  const composable = composableFn({ paginated });
+  const composable = factory();
 
   // ── Derived state ──────────────────────────────────────────────────────────
 

package/src/generators/use-async-data/runtime/useApiAsyncData.ts

@@ -37,14 +37,39 @@ type MaybeTransformed<T, Options> = Options extends { transform: (...args: any)
     ? any // With nested paths, type inference is complex, so we use any
     : T;
 
+type PickInput = ReadonlyArray<string> | undefined;
+
+type HasNestedPath<K extends ReadonlyArray<string>> =
+  Extract<K[number], `${string}.${string}`> extends never ? false : true;
+
+type PickedData<T, K extends PickInput> = K extends ReadonlyArray<string>
+  ? HasNestedPath<K> extends true
+    ? any
+    : Pick<T, Extract<K[number], keyof T>>
+  : T;
+
+type InferPick<Options> = Options extends { pick: infer K extends ReadonlyArray<string> }
+  ? K
+  : undefined;
+
+type InferData<T, Options> = Options extends { transform: (...args: any) => infer R }
+  ? R
+  : PickedData<T, InferPick<Options>>;
+
 /**
  * Options for useAsyncData API requests with lifecycle callbacks.
  * Extends all native Nuxt useFetch options plus our custom callbacks, transform, and pick.
  * Native options like baseURL, method, body, headers, query, lazy, server, immediate, dedupe, etc. are all available.
  * watch: boolean (true = auto-watch reactive params, false = disable auto-refresh)
  */
-export type ApiAsyncDataOptions<T> = BaseApiRequestOptions<T> &
-  Omit<UseFetchOptions<T>, 'transform' | 'pick' | 'watch'> & {
+export type ApiAsyncDataOptions<
+  T,
+  DataT = T,
+  PickT extends PickInput = undefined,
+> = Omit<BaseApiRequestOptions<T>, 'transform' | 'pick'> &
+  Omit<UseFetchOptions<T, DataT>, 'transform' | 'pick' | 'watch'> & {
+    pick?: PickT;
+    transform?: (data: PickedData<T, PickT>) => DataT;
     /**
      * Enable automatic refresh when reactive params/url change (default: true).
      * Set to false to disable auto-refresh entirely.
@@ -61,10 +86,13 @@ export type ApiAsyncDataOptions<T> = BaseApiRequestOptions<T> &
  * - Global headers from useApiHeaders or $getApiHeaders
  * - Watch pattern for reactive parameters
  */
-export function useApiAsyncData<T>(
+export function useApiAsyncData<
+  T,
+  Options extends ApiAsyncDataOptions<T, any, any> = ApiAsyncDataOptions<T>,
+>(
   key: string,
   url: string | (() => string),
-  options?: ApiAsyncDataOptions<T>
+  options?: Options
 ) {
   const {
     method = 'GET',
@@ -295,7 +323,7 @@ export function useApiAsyncData<T>(
   };
 
   // Use Nuxt's useAsyncData with a computed key for proper cache isolation per params
-  const result = useAsyncData<MaybeTransformed<T, ApiAsyncDataOptions<T>>>(computedKey, fetchFn, {
+  const result = useAsyncData<InferData<T, Options>>(computedKey, fetchFn, {
     immediate,
     lazy,
     server,

package/src/generators/use-async-data/runtime/useApiAsyncDataRaw.ts

@@ -48,18 +48,35 @@ type MaybeTransformedRaw<T, Options> = Options extends { transform: (...args: an
     ? RawResponse<any> // With nested paths, type inference is complex
     : RawResponse<T>;
 
+type PickInput = ReadonlyArray<string> | undefined;
+
+type HasNestedPath<K extends ReadonlyArray<string>> =
+  Extract<K[number], `${string}.${string}`> extends never ? false : true;
+
+type PickedData<T, K extends PickInput> = K extends ReadonlyArray<string>
+  ? HasNestedPath<K> extends true
+    ? any
+    : Pick<T, Extract<K[number], keyof T>>
+  : T;
+
 /**
  * Options for useAsyncData Raw API requests.
  * Extends all native Nuxt useFetch options plus our custom callbacks, transform, and pick.
  * onSuccess receives data AND the full response (headers, status, statusText).
  */
-export type ApiAsyncDataRawOptions<T> = Omit<BaseApiRequestOptions<T>, 'onSuccess'> &
-  Omit<UseFetchOptions<T>, 'transform' | 'pick' | 'onSuccess'> & {
+export type ApiAsyncDataRawOptions<
+  T,
+  DataT = T,
+  PickT extends PickInput = undefined,
+> = Omit<BaseApiRequestOptions<T>, 'onSuccess' | 'transform' | 'pick'> &
+  Omit<UseFetchOptions<T, DataT>, 'transform' | 'pick' | 'onSuccess'> & {
+    pick?: PickT;
+    transform?: (data: PickedData<T, PickT>) => DataT;
     /**
      * Called when the request succeeds — receives both data and the full response object.
      */
     onSuccess?: (
-      data: T,
+      data: DataT,
       response: { headers: Headers; status: number; statusText: string; url: string }
     ) => void | Promise<void>;
   };
@@ -76,10 +93,15 @@ export type ApiAsyncDataRawOptions<T> = Omit<BaseApiRequestOptions<T>, 'onSucces
  * - Global headers from useApiHeaders or $getApiHeaders
  * - Watch pattern for reactive parameters
  */
-export function useApiAsyncDataRaw<T>(
+export function useApiAsyncDataRaw<
+  T,
+  DataT = T,
+  PickT extends PickInput = undefined,
+  Options extends ApiAsyncDataRawOptions<T, DataT, PickT> = ApiAsyncDataRawOptions<T, DataT, PickT>,
+>(
   key: string,
   url: string | (() => string),
-  options?: ApiAsyncDataRawOptions<T>
+  options?: Options
 ) {
   const {
     method = 'GET',
@@ -151,7 +173,7 @@ export function useApiAsyncDataRaw<T>(
   };
 
   // Fetch function for useAsyncData
-  const fetchFn = async (): Promise<RawResponse<T>> => {
+  const fetchFn = async (): Promise<RawResponse<DataT>> => {
     // Get URL value for merging callbacks
     const finalUrl = typeof url === 'function' ? url() : url;
 
@@ -253,7 +275,7 @@ export function useApiAsyncDataRaw<T>(
       }
 
       // Construct the raw response object
-      const rawResponse: RawResponse<T> = {
+      const rawResponse: RawResponse<DataT> = {
         data,
         headers: response.headers,
         status: response.status,
@@ -290,7 +312,7 @@ export function useApiAsyncDataRaw<T>(
   };
 
   // Use Nuxt's useAsyncData with a computed key for proper cache isolation per params
-  const result = useAsyncData<MaybeTransformedRaw<T, ApiAsyncDataRawOptions<T>>>(computedKey, fetchFn, {
+  const result = useAsyncData<MaybeTransformedRaw<T, Options>>(computedKey, fetchFn, {
     immediate,
     lazy,
     server,