fix(rest): SoftPathArgs for widened path inference in RestEndpoint subclasses (#3847)

* fix(rest): Guard RestEndpoint/ConstructorOptions against O=any inference

Add `unknown extends O ? any :` before the searchParams conditional in
RestEndpoint<O> and RestEndpointConstructorOptions<O>. When subclassing
with `O extends RestGenerics = any`, this catches O=any before it reaches
PathArgs, preventing the restrictive index-signature type.

Includes detailed comment explaining the partial inference limitation
where TypeScript may widen path literals to `string` due to complex
conditional constructor parameter types.

Follows up on #3845 which fixed PathArgs<any> but missed the higher-level
propagation through RestEndpointTypes.

Made-with: Cursor

* fix(rest): SoftPathArgs collapses widened path to unknown for subclass constructors

Introduce SoftPathArgs<P> that resolves PathArgs<string> to `unknown`,
preventing union overloads in ParamFetchWithBody when path widens.
Infer method as POST when explicit body is provided.

Add comprehensive type tests for widened-path endpoints (all callback
overrides: getOptimisticResponse, key, url, process) and resource()
with AuthdEndpoint subclass (extend per-endpoint, object form,
function form).

Update src-4.0-types legacy replacement with SoftPathArgs export.

Made-with: Cursor

* fix: Cover more cases

* docs: Changeset from user view

* fix: Method property type lacks body-based inference, causing inconsistency

Author: ntucker

.changeset/fix-pathargs-widened-string.md

@@ -0,0 +1,41 @@
+---
+'@data-client/rest': patch
+---
+
+Fix TypeScript for `RestEndpoint` subclasses when the path is inferred as `string`
+
+If you extend `RestEndpoint` with a generic such as `O extends RestGenerics = any`, TypeScript can widen a path literal to `string`. Constructor callbacks like `getOptimisticResponse`, `key`, `url`, and `process` could then get the wrong parameter types (or unusable unions), even though calling the endpoint still worked at runtime.
+
+The same problem could show up when you set `searchParams: undefined` explicitly next to a `body` and a widened path. Both cases now type-check as you would expect.
+
+```typescript
+import { Entity } from '@data-client/endpoint';
+import { RestEndpoint, RestGenerics } from '@data-client/rest';
+
+class Item extends Entity {
+  readonly id = '';
+}
+
+class AppRestEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {}
+
+new AppRestEndpoint({
+  path: '/items' as string,
+  schema: Item,
+  body: {} as { name: string },
+  getOptimisticResponse(_snap, body) {
+    body.name;
+    return body;
+  },
+});
+
+new AppRestEndpoint({
+  path: '/search' as string,
+  searchParams: undefined,
+  schema: Item,
+  body: {} as { q: string },
+  getOptimisticResponse(_snap, body) {
+    body.q;
+    return body;
+  },
+});
+```

.cursor/skills/changeset/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: changeset
-description: Create changesets for version bump, release notes, changelog, semver patch/minor/major, breaking changes, documentation and skill updates after code changes
+description: Create user-focused changesets (changelog entries) for semver bumps, release notes, breaking changes, and docs; prefer impact and code examples over implementation detail
 disable-model-invocation: true
 ---
 
@@ -27,6 +27,7 @@ Generate changesets, update documentation, draft blog entries, and update skills
    - Select all affected packages (direct + transitive)
    - Choose appropriate version bump (patch/minor/major)
      - For packages under 1.0, use minor for breaking changes
+   - When writing the markdown body, follow **Changeset body quality** below (user-visible outcome, code examples when helpful, no internal implementation narrative)
 
 4. **Update documentation**
    - Update primary docs in `docs/` for any changed public APIs
@@ -47,19 +48,26 @@ Generate changesets, update documentation, draft blog entries, and update skills
    - If new APIs or patterns are introduced that agents should know about, add them to the relevant skill
    - Skill changes don't need changesets — they are development tooling, not published packages
 
-## Writing Perspective
-All user-facing text (changesets, blog entries, docs) should be written from the library user's point of view. Describe what was broken or what they can now do — not internal type mechanics or implementation details. Think "what does a developer using this package experience?"
+## Writing perspective
+All user-facing text (changesets, blog entries, docs) should be written from the library user's point of view. Answer: **what did the user see go wrong, and what works for them now?** Avoid internal names (conditional types, branch names, helper types like `SoftPathArgs`, file paths, PR numbers) unless the audience is maintainers reading a technical appendix — changeset bodies are for consumers reading the changelog.
 
-## Changeset Format
+## Changeset body quality
+1. **Lead with impact** — One short title line, then 1–3 sentences on behavior: errors gone, typings improved, new capability, migration note.
+2. **User vocabulary** — Name public APIs (`RestEndpoint`, `resource()`, hook names). Do not explain how the fix was implemented.
+3. **When to add code** — Prefer a minimal example when the change is TypeScript-only or subtle: show the pattern that was broken and now works (subclass, `extend`, option object). Skip examples for trivial renames or obvious one-line fixes.
+4. **Examples** — Realistic imports and types; omit unrelated options. For fixes, you can show one “now types correctly” snippet instead of a long before/after if the before state was “TypeScript error on …”.
+5. **Breaking changes** — Still say what the user must do; use Before/After sections with code when the migration is non-obvious.
+
+## Changeset format
 - **First line**: Action verb ("Add", "Fix", "Update", "Remove")
 - **Breaking**: Prefix with `BREAKING CHANGE:` or `BREAKING:`
-- **Body**: 1–3 lines describing outcome, not implementation
-- **New exports**: Use "New exports:" with bullet list
+- **Body**: User outcome first; implementation almost never belongs here
+- **New exports**: Use "New exports:" with a bullet list
 
-## Code Examples in Changesets
-- Fixes: `// Before: ... ❌` `// After: ... ✓`
-- Breaking changes: Use `#### Before` and `#### After` headers
-- Multiple use cases: Separate with brief labels
+## Code examples in changesets
+- **Fixes**: Optional `// Before:` / `// After:` comments in one block, or two small blocks — keep them copy-paste plausible
+- **Breaking changes**: Use `#### Before` and `#### After` headers with complete snippets
+- **Multiple scenarios**: Short intro line per scenario, or separate fenced blocks with a one-line label above each
 
 ## Markdown Formatting
 Follow `@.cursor/rules/markdown-formatting.mdc` for all markdown content.

packages/rest/src-4.0-types/pathTypes.d.ts

@@ -6,6 +6,12 @@ export declare type PathArgs<S extends string> = PathKeys<S> extends never
   ? unknown
   : KeysToArgs<PathKeys<S>>;
 
+/** Like PathArgs but widened `path: string` collapses to `unknown` */
+export declare type SoftPathArgs<P extends string> =
+  unknown extends P ? any
+  : string extends P ? unknown
+  : PathArgs<P>;
+
 export declare type KeysToArgs<Key extends string> = {
   [K in Key]?: string | number;
 };

packages/rest/src/RestEndpointTypes.ts

@@ -11,7 +11,7 @@ import {
   OptionsToBodyArgument,
   OptionsToFunction,
 } from './OptionsToFunction.js';
-import { PathArgs } from './pathTypes.js';
+import { PathArgs, SoftPathArgs } from './pathTypes.js';
 import { EndpointUpdateFunction } from './RestEndpointTypeHelp.js';
 
 export interface RestInstanceBase<
@@ -520,6 +520,18 @@ type OptionsBodyDefault<O extends RestGenerics> =
   : O['method'] extends 'POST' | 'PUT' | 'PATCH' ? O & { body: any }
   : O & { body: undefined };
 
+/** When `method` is omitted from `O`, infer it (must stay aligned with `OptionsToBodyArgument`). */
+type InferRestMethodWhenOmitted<O extends RestGenerics> =
+  O extends { sideEffect: true } ? 'POST'
+  : 'body' extends keyof O ?
+    [O['body']] extends [undefined] ?
+      'GET'
+    : 'POST'
+  : 'GET';
+
+type MethodArgForBodyInference<O extends RestGenerics> =
+  'method' extends keyof O ? O['method'] : InferRestMethodWhenOmitted<O>;
+
 type OptionsToAdderBodyArgument<O extends { body?: any }> =
   'body' extends keyof O ? O['body'] : any;
 
@@ -558,20 +570,21 @@ export interface RestEndpointOptions<
   update?: EndpointUpdateFunction<F, S>;
 }
 
+// When subclassing RestEndpoint with `O extends RestGenerics = any`, O defaults
+// to `any`. The `unknown extends O ? any` guard catches O=any before it reaches
+// PathArgs (see #3782). SoftPathArgs collapses PathArgs<string> to `unknown`
+// when a concrete body is present, preventing union overloads that break
+// getOptimisticResponse callbacks. Method inference treats explicit body as POST.
 export type RestEndpointConstructorOptions<O extends RestGenerics = any> =
   RestEndpointOptions<
     RestFetch<
-      'searchParams' extends keyof O ?
+      unknown extends O ? any
+      : 'searchParams' extends keyof O ?
         [O['searchParams']] extends [undefined] ?
-          PathArgs<O['path']>
-        : O['searchParams'] & PathArgs<O['path']>
-      : PathArgs<O['path']>,
-      OptionsToBodyArgument<
-        O,
-        'method' extends keyof O ? O['method']
-        : O extends { sideEffect: true } ? 'POST'
-        : 'GET'
-      >,
+          SoftPathArgs<O['path']>
+        : O['searchParams'] & SoftPathArgs<O['path']>
+      : SoftPathArgs<O['path']>,
+      OptionsToBodyArgument<O, MethodArgForBodyInference<O>>,
       O['process'] extends {} ? ReturnType<O['process']>
       : any /*Denormalize<O['schema']>*/
     >,
@@ -586,26 +599,22 @@ export interface RestEndpoint<
   O extends RestGenerics = any,
 > extends RestInstance<
   RestFetch<
-    'searchParams' extends keyof O ?
+    unknown extends O ? any
+    : 'searchParams' extends keyof O ?
       [O['searchParams']] extends [undefined] ?
         PathArgs<O['path']>
       : O['searchParams'] & PathArgs<O['path']>
     : PathArgs<O['path']>,
-    OptionsToBodyArgument<
-      O,
-      'method' extends keyof O ? O['method']
-      : O extends { sideEffect: true } ? 'POST'
-      : 'GET'
-    >,
+    OptionsToBodyArgument<O, MethodArgForBodyInference<O>>,
     O['process'] extends {} ? ReturnType<O['process']>
     : any /*Denormalize<O['schema']>*/
   >,
   'schema' extends keyof O ? O['schema'] : undefined,
   'sideEffect' extends keyof O ? Extract<O['sideEffect'], boolean | undefined>
-  : MethodToSide<O['method']>,
+  : MethodToSide<MethodArgForBodyInference<O>>,
   'method' extends keyof O ? O
   : O & {
-      method: O extends { sideEffect: true } ? 'POST' : 'GET';
+      method: InferRestMethodWhenOmitted<O>;
     }
 > {}
 

packages/rest/src/pathTypes.ts

@@ -18,6 +18,13 @@ export type PathArgs<S extends string> =
     unknown
   : KeysToArgs<PathKeys<S>>;
 
+/** Like {@link PathArgs} but widened `path: string` collapses to `unknown`,
+ *  preventing `(params, body) | (body)` union overloads in ParamFetchWithBody. */
+export type SoftPathArgs<P extends string> =
+  unknown extends P ? any
+  : string extends P ? unknown
+  : PathArgs<P>;
+
 /** Computes the union of keys for a path string */
 export type PathKeys<S extends string> =
   string extends S ? string