diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 2431f00..0b38dc8 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -68,7 +68,8 @@ jobs:
           dotnet build samples/ContractApi --configuration Release
           dotnet run --project JsonApiToolkit.TypeGen --configuration Release --no-build -- \
             --assembly samples/ContractApi/bin/Release/net10.0/ContractApi.dll \
-            --out samples/ContractApi/api-types.gen.ts --check
+            --out samples/ContractApi/api-types.gen.ts \
+            --client-import ../../clients/typescript/src/index.ts --check
 
   status:
     name: Build and Test
@@ -83,11 +84,11 @@ jobs:
           exit 1
 
   publish:
-    if: github.event_name == 'release'
+    if: github.event_name == 'release' && !startsWith(github.event.release.tag_name, 'typescript-')
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write  # OIDC token for NuGet trusted publishing
+      id-token: write
 
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -100,10 +101,14 @@ jobs:
       - name: Restore
         run: dotnet restore --locked-mode
 
-      - name: Build and Pack
+      - name: Build and Pack JsonApiToolkit
+        if: ${{ !startsWith(github.event.release.tag_name, 'typegen-') }}
         run: dotnet pack JsonApiToolkit/JsonApiToolkit.csproj -c Release --no-restore
 
-      # Exchange OIDC token for a short-lived NuGet API key
+      - name: Build and Pack JsonApiToolkit.TypeGen
+        if: startsWith(github.event.release.tag_name, 'typegen-')
+        run: dotnet pack JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj -c Release --no-restore
+
       - name: NuGet login
         id: login
         uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0
@@ -111,7 +116,7 @@ jobs:
           user: ${{ secrets.NUGET_USER }}
 
       - name: Publish to NuGet.org
-        run: dotnet nuget push "JsonApiToolkit/bin/Release/*.nupkg"
+        run: dotnet nuget push "JsonApiToolkit*/bin/Release/*.nupkg"
           --source https://api.nuget.org/v3/index.json
           --api-key ${{ steps.login.outputs.NUGET_API_KEY }}
           --skip-duplicate
diff --git a/.github/workflows/next-snapshot.yml b/.github/workflows/next-snapshot.yml
new file mode 100644
index 0000000..6ebd26b
--- /dev/null
+++ b/.github/workflows/next-snapshot.yml
@@ -0,0 +1,120 @@
+name: Next Snapshot
+
+on:
+  push:
+    branches:
+      - next
+
+concurrency:
+  group: next-snapshot
+  cancel-in-progress: false
+
+jobs:
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      toolkit: ${{ steps.filter.outputs.toolkit }}
+      typegen: ${{ steps.filter.outputs.typegen }}
+      typescript: ${{ steps.filter.outputs.typescript }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
+        id: filter
+        with:
+          base: ${{ github.ref_name }}
+          filters: |
+            toolkit:
+              - 'JsonApiToolkit/**'
+              - 'Directory.Build.props'
+            typegen:
+              - 'JsonApiToolkit.TypeGen/**'
+              - 'Directory.Build.props'
+            typescript:
+              - 'clients/typescript/**'
+
+  dotnet:
+    name: Publish .NET Snapshot
+    needs: changes
+    if: needs.changes.outputs.toolkit == 'true' || needs.changes.outputs.typegen == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Restore
+        run: dotnet restore --locked-mode
+
+      - name: Test
+        run: dotnet test --configuration Release --verbosity normal --no-restore
+
+      - name: Pack JsonApiToolkit
+        if: needs.changes.outputs.toolkit == 'true'
+        run: |
+          BASE=$(sed -n 's:.*<Version>\(.*\)</Version>.*:\1:p' JsonApiToolkit/JsonApiToolkit.csproj)
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE"
+          dotnet pack JsonApiToolkit/JsonApiToolkit.csproj -c Release --no-restore \
+            -p:Version="$MAJOR.$MINOR.$((PATCH + 1))-next.${{ github.run_number }}"
+
+      - name: Pack JsonApiToolkit.TypeGen
+        if: needs.changes.outputs.typegen == 'true'
+        run: |
+          BASE=$(sed -n 's:.*<Version>\(.*\)</Version>.*:\1:p' JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj)
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE"
+          dotnet pack JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj -c Release --no-restore \
+            -p:Version="$MAJOR.$MINOR.$((PATCH + 1))-next.${{ github.run_number }}"
+
+      - name: NuGet login
+        id: login
+        uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0
+        with:
+          user: ${{ secrets.NUGET_USER }}
+
+      - name: Publish to NuGet.org
+        run: dotnet nuget push "JsonApiToolkit*/bin/Release/*.nupkg"
+          --source https://api.nuget.org/v3/index.json
+          --api-key ${{ steps.login.outputs.NUGET_API_KEY }}
+          --skip-duplicate
+
+  typescript:
+    name: Publish TypeScript Snapshot
+    needs: changes
+    if: needs.changes.outputs.typescript == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        working-directory: clients/typescript
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2
+        with:
+          deno-version: v2.x
+
+      - name: Test
+        run: deno task test
+
+      - name: Set Snapshot Version
+        run: |
+          BASE=$(jq -r .version deno.json)
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE"
+          jq --arg v "$MAJOR.$MINOR.$((PATCH + 1))-next.${{ github.run_number }}" \
+            '.version = $v' deno.json > deno.json.tmp
+          mv deno.json.tmp deno.json
+
+      - name: Publish to JSR
+        run: deno publish --allow-dirty
diff --git a/.github/workflows/typescript-release.yml b/.github/workflows/typescript-release.yml
new file mode 100644
index 0000000..57a8918
--- /dev/null
+++ b/.github/workflows/typescript-release.yml
@@ -0,0 +1,35 @@
+name: TypeScript Release
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: ts-release-${{ github.ref }}
+  cancel-in-progress: false
+
+defaults:
+  run:
+    working-directory: clients/typescript
+
+jobs:
+  publish:
+    if: startsWith(github.event.release.tag_name, 'typescript-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Deno
+        uses: denoland/setup-deno@22d081ff2d3a40755e97629de92e3bcbfa7cf2ed # v2
+        with:
+          deno-version: v2.x
+
+      - name: Test
+        run: deno task test
+
+      - name: Publish to JSR
+        run: deno publish
diff --git a/JsonApiToolkit.TypeGen.Tests/CliIntegrationTests.cs b/JsonApiToolkit.TypeGen.Tests/CliIntegrationTests.cs
index ff78c48..9fe43cb 100644
--- a/JsonApiToolkit.TypeGen.Tests/CliIntegrationTests.cs
+++ b/JsonApiToolkit.TypeGen.Tests/CliIntegrationTests.cs
@@ -26,9 +26,11 @@ public void Run_resolves_JsonApiResource_types_from_a_separately_built_assembly(
             Assert.Contains("export interface Author", generated);
             Assert.Contains("export interface Comment", generated);
             Assert.Contains(
-                "Article: { type: \"articles\", relationships: [\"author\", \"comments\"] }",
+                "export const Article: JsonApiResourceDescriptor<Article> = {",
                 generated
             );
+            Assert.Contains("  toOne: [\"author\"],", generated);
+            Assert.Contains("  toMany: [\"comments\"],", generated);
 
             // --check passes right after generation...
             Assert.Equal(
diff --git a/JsonApiToolkit.TypeGen.Tests/TypeScriptEmitterTests.cs b/JsonApiToolkit.TypeGen.Tests/TypeScriptEmitterTests.cs
index ddf15de..3f09fa1 100644
--- a/JsonApiToolkit.TypeGen.Tests/TypeScriptEmitterTests.cs
+++ b/JsonApiToolkit.TypeGen.Tests/TypeScriptEmitterTests.cs
@@ -51,15 +51,27 @@ public void Generate_maps_attributes_and_relationships_and_skips_unmapped_types(
             (typeof(Part), "parts"),
         };
 
-        var ts = TypeScriptEmitter.Generate(resources);
+        var ts = TypeScriptEmitter.Generate(resources, "@intility/json-api-client");
 
+        Assert.Contains(
+            "import type { JsonApiResourceDescriptor } from \"@intility/json-api-client\";",
+            ts
+        );
         Assert.Contains("description: string | null;", ts);
         Assert.Contains("retiredAt: string | null;", ts);
         Assert.Contains("tags: string[];", ts);
         Assert.Contains("ownerId: number;", ts);
         Assert.Contains("owner: Owner | null;", ts);
         Assert.Contains("parts: Part[];", ts);
-        Assert.Contains("Widget: { type: \"widgets\", relationships: [\"owner\", \"parts\"] }", ts);
+
+        Assert.Contains("export const Widget: JsonApiResourceDescriptor<Widget> = {", ts);
+        Assert.Contains("  type: \"widgets\",", ts);
+        Assert.Contains(
+            "  attributes: [\"name\", \"description\", \"retiredAt\", \"tags\", \"ownerId\"],",
+            ts
+        );
+        Assert.Contains("  toOne: [\"owner\"],", ts);
+        Assert.Contains("  toMany: [\"parts\"],", ts);
 
         // UnmappedThing has no [JsonApiResource]: the property is dropped, not guessed at.
         Assert.DoesNotContain("extra", ts);
diff --git a/JsonApiToolkit.TypeGen/Cli.cs b/JsonApiToolkit.TypeGen/Cli.cs
index b128c8d..f615e59 100644
--- a/JsonApiToolkit.TypeGen/Cli.cs
+++ b/JsonApiToolkit.TypeGen/Cli.cs
@@ -14,6 +14,7 @@ public static int Run(string[] args)
     {
         string? assemblyPath = null;
         string? outPath = null;
+        string clientImport = "@intility/json-api-client";
         bool check = false;
 
         for (int i = 0; i < args.Length; i++)
@@ -26,6 +27,9 @@ public static int Run(string[] args)
                 case "--out":
                     outPath = args[++i];
                     break;
+                case "--client-import":
+                    clientImport = args[++i];
+                    break;
                 case "--check":
                     check = true;
                     break;
@@ -38,7 +42,8 @@ public static int Run(string[] args)
         if (assemblyPath is null || outPath is null)
         {
             Console.Error.WriteLine(
-                "Usage: jsonapi-typegen --assembly <path/to/Api.dll> --out <path/to/api-types.gen.ts> [--check]"
+                "Usage: jsonapi-typegen --assembly <path/to/Api.dll> --out <path/to/api-types.gen.ts> "
+                    + "[--client-import <specifier>] [--check]"
             );
             return 1;
         }
@@ -61,7 +66,7 @@ public static int Run(string[] args)
             return 1;
         }
 
-        string generated = TypeScriptEmitter.Generate(resources);
+        string generated = TypeScriptEmitter.Generate(resources, clientImport);
 
         if (check)
         {
diff --git a/JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj b/JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj
index 0bab50d..d3b4df2 100644
--- a/JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj
+++ b/JsonApiToolkit.TypeGen/JsonApiToolkit.TypeGen.csproj
@@ -9,12 +9,22 @@
     <ToolCommandName>jsonapi-typegen</ToolCommandName>
     <PackageId>Intility.JsonApiToolkit.TypeGen</PackageId>
     <Title>JsonApiToolkit TypeGen</Title>
-    <Version>2.1.8</Version>
+    <Version>0.1.0</Version>
     <Authors>Intility</Authors>
     <Company>Intility</Company>
     <Description>Generates TypeScript resource types from [JsonApiResource]-attributed C# models.</Description>
+    <PackageTags>jsonapi;json-api;typescript;codegen;dotnet-tool</PackageTags>
+    <RepositoryUrl>https://github.com/intility/json-api-toolkit</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageProjectUrl>https://github.com/intility/json-api-toolkit</PackageProjectUrl>
+    <PackageIcon>intility-logo.png</PackageIcon>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
   </PropertyGroup>
+  <ItemGroup>
+    <None Include="README.md" Pack="true" PackagePath="\"/>
+    <None Include="..\assets\intility-logo.png" Pack="true" Visible="false" PackagePath="\"/>
+  </ItemGroup>
   <ItemGroup>
     <!-- Reuses EntityMapper's attribute/relationship classification so the
          generated types can never drift from what the toolkit actually
diff --git a/JsonApiToolkit.TypeGen/README.md b/JsonApiToolkit.TypeGen/README.md
new file mode 100644
index 0000000..4d6f88a
--- /dev/null
+++ b/JsonApiToolkit.TypeGen/README.md
@@ -0,0 +1,66 @@
+# JsonApiToolkit TypeGen
+
+A .NET tool that generates TypeScript resource types from
+`[JsonApiResource]`-attributed C# models. It reuses the exact
+attribute/relationship classification that
+[JsonApiToolkit](https://www.nuget.org/packages/Intility.JsonApiToolkit)
+uses at runtime, so the generated types cannot drift from what your API
+serializes on the wire.
+
+## Installation
+
+```bash
+dotnet tool install Intility.JsonApiToolkit.TypeGen --prerelease
+```
+
+## Usage
+
+Build your API project first, then point the tool at the compiled assembly:
+
+```bash
+jsonapi-typegen --assembly bin/Release/net10.0/MyApi.dll --out api-types.gen.ts
+```
+
+Pass `--check` to verify the output is up to date without writing it. This
+exits non-zero on drift, which makes it useful as a CI gate:
+
+```bash
+jsonapi-typegen --assembly bin/Release/net10.0/MyApi.dll --out api-types.gen.ts --check
+```
+
+## How it works
+
+Mark your resource models with `[JsonApiResource]` in the API project. The
+tool loads the assembly, finds the attributed types, and emits, per
+resource, one TypeScript interface and one descriptor constant of the same
+name:
+
+```ts
+export interface Article {
+  id: string;
+  title: string;
+  publishedAt: string | null;
+  author: Author | null;
+  comments: Comment[];
+}
+
+export const Article: JsonApiResourceDescriptor<Article> = {
+  type: "articles",
+  attributes: ["title", "publishedAt"],
+  toOne: ["author"],
+  toMany: ["comments"],
+};
+```
+
+Attributes and relationships are classified the same way JsonApiToolkit
+maps them. The descriptor is what
+[`@intility/json-api-client`](https://jsr.io/@intility/json-api-client)
+needs to keep hydration honest: `client.resource(Article)` infers the type,
+uses the wire type as the path, and fills in what the wire omits
+(null-stripped attributes as `null`, un-included relationships as `null` or
+`[]`). Set `UseResourceAttributeTypeNames` in the API's `JsonApiOptions` so
+included resources carry the same type names and match their descriptors.
+
+The descriptor type is imported from `@intility/json-api-client` by default.
+Pass `--client-import <specifier>` to point at a different module (for
+example a relative path inside a monorepo).
diff --git a/JsonApiToolkit.TypeGen/TypeScriptEmitter.cs b/JsonApiToolkit.TypeGen/TypeScriptEmitter.cs
index 3f5f106..7447ccf 100644
--- a/JsonApiToolkit.TypeGen/TypeScriptEmitter.cs
+++ b/JsonApiToolkit.TypeGen/TypeScriptEmitter.cs
@@ -12,7 +12,17 @@ namespace JsonApiToolkit.TypeGen;
 /// </summary>
 public static class TypeScriptEmitter
 {
-    public static string Generate(IReadOnlyList<(Type Type, string WireType)> resources)
+    /// <summary>
+    /// Emits one interface and one descriptor constant per resource. The
+    /// descriptor shares the interface's name (TypeScript keeps types and
+    /// values in separate namespaces) so `client.resource(Article)` infers
+    /// the `Article` type.
+    /// </summary>
+    /// <param name="clientImport">Module specifier the descriptor type is imported from.</param>
+    public static string Generate(
+        IReadOnlyList<(Type Type, string WireType)> resources,
+        string clientImport
+    )
     {
         var wireTypeByType = resources.ToDictionary(r => r.Type, r => r.WireType);
         var ordered = resources.OrderBy(r => r.Type.Name, StringComparer.Ordinal).ToList();
@@ -20,16 +30,18 @@ public static string Generate(IReadOnlyList<(Type Type, string WireType)> resour
 
         var sb = new StringBuilder();
         sb.AppendLine("// AUTO-GENERATED by `dotnet jsonapi-typegen`. Do not edit by hand.");
+        sb.AppendLine($"import type {{ JsonApiResourceDescriptor }} from \"{clientImport}\";");
         sb.AppendLine();
 
-        foreach ((Type? type, string _) in ordered)
+        foreach ((Type? type, string? wireType) in ordered)
         {
             EmitInterface(sb, type, wireTypeByType, nullability);
             sb.AppendLine();
+            EmitDescriptor(sb, type, wireType, wireTypeByType);
+            sb.AppendLine();
         }
 
-        EmitResourceMap(sb, ordered, wireTypeByType);
-        return sb.ToString();
+        return sb.ToString().TrimEnd() + Environment.NewLine;
     }
 
     private static void EmitInterface(
@@ -42,7 +54,7 @@ NullabilityInfoContext nullability
         sb.AppendLine($"export interface {type.Name} {{");
         sb.AppendLine("  id: string;"); // JSON:API ids are always strings on the wire
 
-        foreach (PropertyInfo prop in EntityMapper.GetAttributeProperties(type))
+        foreach (PropertyInfo prop in MappedAttributes(type))
         {
             (string TsType, bool Nullable)? mapped = MapAttributeType(prop, nullability);
             if (mapped is null)
@@ -83,27 +95,50 @@ NullabilityInfoContext nullability
         sb.AppendLine("}");
     }
 
-    private static void EmitResourceMap(
+    /// <summary>
+    /// The runtime shape the client needs to make hydration honest: null-stripped
+    /// attributes come back as null, un-included relationships as null or [].
+    /// </summary>
+    private static void EmitDescriptor(
         StringBuilder sb,
-        List<(Type Type, string WireType)> ordered,
+        Type type,
+        string wireType,
         Dictionary<Type, string> wireTypeByType
     )
     {
-        sb.AppendLine("export const ResourceMap = {");
-        foreach ((Type? type, string? wireType) in ordered)
-        {
-            IEnumerable<string> relationships = EntityMapper
+        var nullability = new NullabilityInfoContext();
+        IEnumerable<string> attributes = MappedAttributes(type)
+            .Where(p => MapAttributeType(p, nullability) is not null)
+            .Select(Name);
+
+        List<PropertyInfo> relationships =
+        [
+            .. EntityMapper
                 .GetRelationshipProperties(type)
                 .Where(p =>
                     wireTypeByType.ContainsKey(TypeHelpers.GetNavigationTargetType(p.PropertyType))
-                )
-                .Select(p => $"\"{EntityMapper.GetAttributeName(p)}\"");
+                ),
+        ];
+        IEnumerable<string> toOne = relationships
+            .Where(p => !TypeHelpers.IsCollectionType(p.PropertyType))
+            .Select(Name);
+        IEnumerable<string> toMany = relationships
+            .Where(p => TypeHelpers.IsCollectionType(p.PropertyType))
+            .Select(Name);
+
+        sb.AppendLine($"export const {type.Name}: JsonApiResourceDescriptor<{type.Name}> = {{");
+        sb.AppendLine($"  type: \"{wireType}\",");
+        sb.AppendLine($"  attributes: [{string.Join(", ", attributes)}],");
+        sb.AppendLine($"  toOne: [{string.Join(", ", toOne)}],");
+        sb.AppendLine($"  toMany: [{string.Join(", ", toMany)}],");
+        sb.AppendLine("};");
+
+        static string Name(PropertyInfo p) => $"\"{EntityMapper.GetAttributeName(p)}\"";
+    }
 
-            sb.AppendLine(
-                $"  {type.Name}: {{ type: \"{wireType}\", relationships: [{string.Join(", ", relationships)}] }},"
-            );
-        }
-        sb.AppendLine("} as const;");
+    private static IEnumerable<PropertyInfo> MappedAttributes(Type type)
+    {
+        return EntityMapper.GetAttributeProperties(type);
     }
 
     /// <summary>
diff --git a/clients/typescript/README.md b/clients/typescript/README.md
index 3aa0784..2fd53e1 100644
--- a/clients/typescript/README.md
+++ b/clients/typescript/README.md
@@ -1,10 +1,10 @@
-# jsonapi-ts-tools
+# json-api-client
 
-[![🚀 Release](https://github.com/intility/jsonapi-ts-tools/actions/workflows/release.yml/badge.svg)](https://github.com/intility/jsonapi-ts-tools/actions/workflows/release.yml)
+[![TypeScript Release](https://github.com/intility/json-api-toolkit/actions/workflows/typescript-release.yml/badge.svg)](https://github.com/intility/json-api-toolkit/actions/workflows/typescript-release.yml)
 
-**jsonapi-ts-tools** is a lightweight, Deno-based TypeScript library designed to
+**json-api-client** is a lightweight, Deno-based TypeScript library designed to
 make working with
-[JsonApiToolkit](https://github.com/intility/Intility.JsonApiToolkit) responses
+[JsonApiToolkit](https://github.com/intility/json-api-toolkit) responses
 in TypeScript applications easier.
 
 ## Features
@@ -18,19 +18,25 @@ in TypeScript applications easier.
 ## Prerequisites
 
 - **JsonApiToolkit**: This library is designed to work with
-  [JsonApiToolkit](https://github.com/intility/Intility.JsonApiToolkit). Make
+  [JsonApiToolkit](https://github.com/intility/json-api-toolkit). Make
   sure the api you want to interact with is using JsonApiToolkit.
 
 ## Getting Started
 
-You can read more about jsonapi-ts-tools & JsonApiToolkit
-[**here**](https://intility.github.io/Intility.JsonApiToolkit/docs/integrations/ts-tools.html),
+You can read more about json-api-client & JsonApiToolkit
+[**here**](https://intility.github.io/json-api-toolkit/),
 or follow the instructions below for a quick start.
 
 ### Installation
 
+The package is published on [JSR](https://jsr.io/@intility/json-api-client):
+
 ```bash
-npm install @intility/jsonapi-ts-tools
+# Deno
+deno add jsr:@intility/json-api-client
+
+# Node.js (via the jsr CLI)
+npx jsr add @intility/json-api-client
 ```
 
 ### Define your types
@@ -73,7 +79,7 @@ import {
   hydrateResponse,
   JsonApiArrayResponse,
   JsonApiSingleResponse,
-} from '@intility/jsonapi-ts-tools';
+} from '@intility/json-api-client';
 
 // For list endpoints (returns array of resources)
 export function useHydratedListQuery<THydrated>(
@@ -167,6 +173,55 @@ This will create a query string that looks like this:
 > [!TIP]
 > The query builder supports nested includes using dot notation.
 
+A `Date` filter value serializes to ISO 8601 (`date.toISOString()`), not
+`String(date)`'s locale format. `in`/`nin` values join with commas:
+
+```ts
+new JsonApiQueryBuilder<Todo>().filter("dueDate", "in", [
+  new Date("2025-01-01"),
+  new Date("2025-02-01"),
+]);
+// filter[dueDate][in]=2025-01-01T00:00:00.000Z,2025-02-01T00:00:00.000Z
+```
+
+> [!WARNING]
+> There is no escaping for a comma inside a value; a string value
+> containing a literal comma breaks the join for `in`/`nin`.
+
+`.sort()` only accepts direct attributes, unlike `.filter()`: the backend
+silently ignores a dot-path sort field instead of walking the relationship,
+so a type-safe "this compiles but does nothing" trap isn't worth having.
+
+Repeat `.sort()` or `.include()` calls append, same as `.filter()`, rather
+than replacing what an earlier call set:
+
+```ts
+new JsonApiQueryBuilder<Todo>().sort("title").sort("-dueDate");
+// same as .sort("title", "-dueDate") -> sort=title,-dueDate
+```
+
+`.filter("owner.name", ...)` is type-checked one relationship level deep.
+Deeper paths (the backend walks dot-paths up to 5 segments, including through
+a to-many relationship via `Any()`, e.g. `"comments.author.name"`) still
+compile, but only the first segment is checked against a real relationship;
+everything past the first dot is on the honor system, same as `in`/`nin`
+comma-joining not escaping commas.
+
+Null checks use dedicated methods, since the `isnull`/`isnotnull` operators
+ignore whatever value you'd otherwise pass:
+
+```ts
+const queryString = new JsonApiQueryBuilder<Todo>()
+  .filterNull("dueDate")
+  .build();
+```
+
+```
+?filter[dueDate][isnull]=true
+```
+
+`filterNotNull("dueDate")` works the same way with `isnotnull`.
+
 ### Sparse fieldsets
 
 Request only the fields you need to reduce payload size:
@@ -184,37 +239,60 @@ const queryString = new JsonApiQueryBuilder<Todo>()
 ?filter[completed]=false&include=owner&fields[todos]=title,dueDate&fields[users]=name
 ```
 
-### Filter groups
+`fields()` also takes a generated resource descriptor (see
+`dotnet jsonapi-typegen`) instead of a hand-written type string, so the wire
+`type` can't drift from what the descriptor says:
 
-Use logical grouping for complex filter expressions:
+```ts
+const queryString = new JsonApiQueryBuilder<Todo>()
+  .fields(TodoDescriptor, ["title", "dueDate"])
+  .build();
+```
+
+### Filtering included resources
+
+`filterIncluded()` trims which resources come back in `included`, without
+touching the primary `data` array. Distinct from dot-path filtering
+(`.filter("owner.name", ...)`), which filters the primary resource itself by
+a related field. Requires the relationship to also be passed to `.include()`.
 
 ```ts
 const queryString = new JsonApiQueryBuilder<Todo>()
-  .or((b) => {
-    b.filter("title", "like", "%urgent%");
-    b.filter("completed", "eq", "false");
-  })
+  .filterIncluded("tags", "label", "eq", "urgent")
+  .include("tags")
   .build();
 ```
 
 ```
-?filter[or][0][title][like]=%urgent%&filter[or][1][completed]=false
+?filter[tags][label][eq]=urgent&include=tags
 ```
 
-You can also nest groups:
+> [!NOTE]
+> The backend's filtered-include only applies to to-many relationships (EF
+> Core's collection `.Where()`); on a to-one relationship, `filterIncluded()`
+> compiles but has no effect.
+
+### Filter groups
+
+Use logical grouping for complex filter expressions:
 
 ```ts
 const queryString = new JsonApiQueryBuilder<Todo>()
   .or((b) => {
-    b.filter("title", "eq", "Important");
-    b.and((inner) => {
-      inner.filter("completed", "eq", "true");
-      inner.filter("dueDate", "gt", "2025-01-01");
-    });
+    b.filter("title", "like", "%urgent%");
+    b.filter("completed", "eq", "false");
   })
   .build();
 ```
 
+```
+?filter[or][0][title][like]=%urgent%&filter[or][1][completed]=false
+```
+
+There is no `.and()`: top-level filters are already AND'd together. Groups
+take flat filter lists only; nesting a group inside `or()`/`not()` is a
+compile error, because the backend only parses one flat level.
+
 ### Error handling
 
 The library provides TypeScript types for JSON:API error responses, matching
@@ -225,7 +303,7 @@ the error structure produced by
 import {
   isJsonApiErrorResponse,
   JsonApiErrorCodes,
-} from "@intility/jsonapi-ts-tools";
+} from "@intility/json-api-client";
 
 const response = await fetch("/api/todos");
 const body = await response.json();
diff --git a/clients/typescript/build_npm.ts b/clients/typescript/build_npm.ts
index d923723..5d76361 100644
--- a/clients/typescript/build_npm.ts
+++ b/clients/typescript/build_npm.ts
@@ -10,17 +10,20 @@ await build({
   },
   test: false,
   package: {
-    name: '@intility/jsonapi-ts-tools',
-    version: Deno.args[0] || '0.0.0',
+    name: '@intility/json-api-client',
+    version: Deno.args[0] || '0.1.0',
+    publishConfig: {
+      access: 'public',
+    },
     description:
-      'jsonapi-ts-tools is a TypeScript library for working with JSON:API.',
+      'json-api-client is a TypeScript library for working with JSON:API.',
     license: 'MIT',
     repository: {
       type: 'git',
-      url: 'git+https://github.com/intility/jsonapi-ts-tools.git',
+      url: 'git+https://github.com/intility/json-api-toolkit.git',
     },
     bugs: {
-      url: 'https://github.com/intility/jsonapi-ts-tools/issues',
+      url: 'https://github.com/intility/json-api-toolkit/issues',
     },
   },
   postBuild() {
diff --git a/clients/typescript/contract/client_contract_test.ts b/clients/typescript/contract/client_contract_test.ts
new file mode 100644
index 0000000..159041e
--- /dev/null
+++ b/clients/typescript/contract/client_contract_test.ts
@@ -0,0 +1,121 @@
+/**
+ * Core client contract: a resource handle's reads and writes against a real
+ * toolkit-backed API, end to end (query building -> fetch -> hydration ->
+ * error parsing).
+ */
+import { assert, assertEquals, assertRejects } from '@std/assert';
+import { createJsonApiClient, JsonApiRequestError } from '../src/index.ts';
+import {
+  BASE_URL,
+  type ContractArticle,
+  PUBLISHED_ARTICLES,
+  STRICT_BASE_URL,
+  TOTAL_ARTICLES,
+} from './helpers.ts';
+import { Article, Author } from '../../../samples/ContractApi/api-types.gen.ts';
+
+const articles = createJsonApiClient({ baseUrl: BASE_URL })
+  .resource<ContractArticle>('articles');
+
+Deno.test('list', async (t) => {
+  await t.step('hydrates data and returns pagination', async () => {
+    const { data, pagination } = await articles.list(
+      (q) => q.filter('published', true).page(1, 5),
+    );
+    assertEquals(data.length, 5);
+    assertEquals(pagination?.totalResources, PUBLISHED_ARTICLES);
+    assertEquals(data[0].title, 'Article 01');
+  });
+
+  await t.step('accepts a pre-built query string for interop', async () => {
+    const { data, pagination } = await articles.list({
+      params: 'page%5Bsize%5D=1',
+    });
+    assertEquals(data.length, 1);
+    assertEquals(pagination?.totalResources, TOTAL_ARTICLES);
+  });
+
+  await t.step('unpaginated request has no pagination', async () => {
+    const { data, pagination } = await articles.list();
+    assertEquals(data.length, TOTAL_ARTICLES);
+    assertEquals(pagination, undefined);
+  });
+});
+
+Deno.test('get', async (t) => {
+  await t.step('hydrates an included relationship', async () => {
+    const article = await articles.get(1, (q) => q.include('author'));
+    assertEquals(article.id, '1');
+    assertEquals(article.author.name, 'Astrid Berg');
+  });
+
+  await t.step('throws JsonApiRequestError with the status', async () => {
+    const error = await assertRejects(
+      () => articles.get(999999),
+      JsonApiRequestError,
+    );
+    assertEquals(error.status, 404);
+  });
+});
+
+Deno.test('generated descriptors (strict instance)', async (t) => {
+  // UseResourceAttributeTypeNames is on here, so included resources carry
+  // the [JsonApiResource] type name and match their descriptor.
+  const generated = createJsonApiClient({
+    baseUrl: STRICT_BASE_URL,
+    resources: [Author],
+  }).resource(Article);
+
+  await t.step('null-stripped attributes come back as null', async () => {
+    const article = await generated.get(2); // even id: publishedAt is null
+    assertEquals(article.publishedAt, null);
+    assertEquals(article.body, 'Body of article 2');
+  });
+
+  await t.step('un-included relationships are null / []', async () => {
+    const article = await generated.get(2);
+    assertEquals(article.author, null);
+    assertEquals(article.comments, []);
+  });
+
+  await t.step(
+    'included resources are filled from their descriptor',
+    async () => {
+      const article = await generated.get(2, (q) => q.include('author'));
+      assertEquals(article.author?.name, 'Bjarne Moen');
+      assertEquals(article.author?.email, null); // stripped on the wire
+    },
+  );
+});
+
+Deno.test('writes', async (t) => {
+  await t.step('post, patch, delete round trip', async () => {
+    const created = await articles.post({
+      title: 'Client contract test article',
+      published: false,
+      authorId: 2,
+      tags: ['contract-client'],
+    });
+    assertEquals(created.title, 'Client contract test article');
+    assert(created.id);
+
+    const updated = await articles.patch(created.id, { viewCount: 7 });
+    assertEquals(updated.viewCount, 7);
+    assertEquals(updated.title, 'Client contract test article');
+
+    await articles.delete(created.id);
+    await assertRejects(() => articles.get(created.id), JsonApiRequestError);
+  });
+
+  await t.step(
+    'validation failure surfaces via hasCode and fieldErrors',
+    async () => {
+      const error = await assertRejects(
+        () => articles.post({ body: 'no title' }),
+        JsonApiRequestError,
+      );
+      assertEquals(error.hasCode('REQUIRED_FIELD_MISSING'), true);
+      assertEquals(Object.keys(error.fieldErrors()), ['title']);
+    },
+  );
+});
diff --git a/clients/typescript/contract/document_contract_test.ts b/clients/typescript/contract/document_contract_test.ts
index bc03565..3d64c1b 100644
--- a/clients/typescript/contract/document_contract_test.ts
+++ b/clients/typescript/contract/document_contract_test.ts
@@ -3,27 +3,28 @@
  * sparse fieldsets, null-stripping.
  */
 import { assert, assertEquals, assertFalse } from '@std/assert';
+import { hydrateResponse, JsonApiQueryBuilder } from '../src/index.ts';
 import {
-  hydrateResponse,
-  type JsonApiArrayResponse,
-  JsonApiQueryBuilder,
-  type JsonApiSingleResponse,
-} from '../src/index.ts';
-import { type ContractArticle, getDoc } from './helpers.ts';
+  type ContractArticle,
+  getDoc,
+  type List,
+  type Single,
+} from './helpers.ts';
+import { Article } from '../../../samples/ContractApi/api-types.gen.ts';
 
 Deno.test('document shape', async (t) => {
   await t.step('primary resources use the controller type string', async () => {
-    const { status, doc } = await getDoc('articles/3');
+    const { status, doc } = await getDoc<Single>('articles/3');
     assertEquals(status, 200);
     assertEquals(doc.data.type, 'articles');
     assertEquals(doc.data.id, '3'); // ids are strings on the wire
-    assertEquals(doc.data.links.self.endsWith('/articles/3'), true);
+    assertEquals(doc.data.links?.self?.endsWith('/articles/3'), true);
   });
 
   await t.step(
     'attributes: camelCase, ISO dates, FK ids leak as attributes',
     async () => {
-      const { doc } = await getDoc('articles/3');
+      const { doc } = await getDoc<Single>('articles/3');
       assertEquals(doc.data.attributes.title, 'Article 03');
       assertEquals(doc.data.attributes.publishedAt, '2025-01-03T12:00:00Z');
       assertEquals(doc.data.attributes.viewCount, 30);
@@ -35,39 +36,39 @@ Deno.test('document shape', async (t) => {
   await t.step(
     'primitive collections are attributes (JSON column detection)',
     async () => {
-      const { doc } = await getDoc('articles/3');
+      const { doc } = await getDoc<Single>('articles/3');
       assertEquals(doc.data.attributes.tags, ['tech', 'news']);
       // empty collections serialize as [], not stripped
-      const { doc: doc23 } = await getDoc('articles/23');
+      const { doc: doc23 } = await getDoc<Single>('articles/23');
       assertEquals(doc23.data.attributes.tags, []);
     },
   );
 
   await t.step('null attributes are stripped from responses', async () => {
     // article 25: body is null; publishedAt is set (odd id)
-    const { doc } = await getDoc('articles/25');
+    const { doc } = await getDoc<Single>('articles/25');
     assertFalse('body' in doc.data.attributes);
     // article 2: publishedAt is null (even id)
-    const { doc: doc2 } = await getDoc('articles/2');
+    const { doc: doc2 } = await getDoc<Single>('articles/2');
     assertFalse('publishedAt' in doc2.data.attributes);
     assertEquals(doc2.data.attributes.published, false);
     // authors/2 has null email
-    const { doc: author } = await getDoc('authors/2');
+    const { doc: author } = await getDoc<Single>('authors/2');
     assertEquals(author.data.attributes, { name: 'Bjarne Moen' });
   });
 
   await t.step(
     'included resources use the camelCased CLR class name, not the controller type',
     async () => {
-      const { doc } = await getDoc('articles/3?include=author');
+      const { doc } = await getDoc<Single>('articles/3?include=author');
       assertEquals(doc.data.type, 'articles');
-      assertEquals(doc.data.relationships.author.data, {
+      assertEquals(doc.data.relationships?.author.data, {
         id: '3',
         type: 'author',
       });
-      assertEquals(doc.included.length, 1);
-      assertEquals(doc.included[0].type, 'author'); // singular CLR name
-      assertEquals(doc.included[0].attributes.name, 'Carmen Diaz');
+      assertEquals(doc.included?.length, 1);
+      assertEquals(doc.included?.[0].type, 'author'); // singular CLR name
+      assertEquals(doc.included?.[0].attributes.name, 'Carmen Diaz');
     },
   );
 
@@ -76,18 +77,21 @@ Deno.test('document shape', async (t) => {
     async () => {
       // include=comments.author: included is populated, but data has no
       // relationships object at all, so the linkage is unrecoverable.
-      const { doc } = await getDoc('articles/3?include=comments.author');
+      const { doc } = await getDoc<Single>(
+        'articles/3?include=comments.author',
+      );
       assertFalse('relationships' in doc.data);
-      const includedTypes = doc.included.map((r: { type: string }) => r.type)
+      const includedTypes = doc.included?.map((r) => r.type)
         .sort();
       assertEquals(includedTypes, ['author', 'author', 'comment', 'comment']);
       // included comments DO carry their own relationships
-      const comment = doc.included.find((r: { type: string }) =>
-        r.type === 'comment'
+      const comment = doc.included?.find((r) => r.type === 'comment');
+      const authorRef = comment?.relationships?.author.data;
+      assert(
+        authorRef && !Array.isArray(authorRef) && authorRef.type === 'author',
       );
-      assertEquals(comment.relationships.author.data.type, 'author');
       // same on collections
-      const { doc: list } = await getDoc(
+      const { doc: list } = await getDoc<List>(
         'articles?include=comments.author&page%5Bsize%5D=2',
       );
       assertFalse('relationships' in list.data[0]);
@@ -100,10 +104,10 @@ Deno.test('sparse fieldsets', async (t) => {
     'fields[type] works for the primary resource via the builder',
     async () => {
       const qs = new JsonApiQueryBuilder<ContractArticle>()
-        .fields<ContractArticle>('articles', ['title', 'publishedAt'])
+        .fields(Article, ['title', 'publishedAt'])
         .page(1, 2)
         .build();
-      const { doc } = await getDoc(`articles?${qs}`);
+      const { doc } = await getDoc<List>(`articles?${qs}`);
       assertEquals(Object.keys(doc.data[0].attributes), [
         'title',
         'publishedAt',
@@ -115,22 +119,22 @@ Deno.test('sparse fieldsets', async (t) => {
     'included resources need the CLR-derived type name, not the wire type',
     async () => {
       // fields[author] (CLR name) trims the included author...
-      const { doc } = await getDoc(
+      const { doc } = await getDoc<Single>(
         'articles/3?include=author&fields%5Bauthor%5D=name',
       );
-      assertEquals(Object.keys(doc.included[0].attributes), ['name']);
+      assertEquals(Object.keys(doc.included?.[0].attributes ?? {}), ['name']);
       // ...fields[authors] (what a JSON:API client would guess) does nothing
-      const { doc: doc2 } = await getDoc(
+      const { doc: doc2 } = await getDoc<Single>(
         'articles/3?include=author&fields%5Bauthors%5D=name',
       );
-      assert(Object.keys(doc2.included[0].attributes).length > 1);
+      assert(Object.keys(doc2.included?.[0].attributes ?? {}).length > 1);
     },
   );
 
   await t.step(
     'id and type are always present regardless of fieldset',
     async () => {
-      const { doc } = await getDoc(
+      const { doc } = await getDoc<List>(
         'articles?fields%5Barticles%5D=title&page%5Bsize%5D=1',
       );
       assertEquals(doc.data[0].id, '1');
@@ -143,13 +147,14 @@ Deno.test('hydration', async (t) => {
   await t.step(
     'single-level include hydrates to a flat nested object',
     async () => {
-      const { doc } = await getDoc('articles/3?include=author');
-      const { data } = hydrateResponse<ContractArticle>(
-        doc as JsonApiSingleResponse,
-      );
+      const { doc } = await getDoc<Single>('articles/3?include=author');
+      const { data } = hydrateResponse<ContractArticle>(doc);
       assertEquals(data.title, 'Article 03');
       assertEquals(data.author.name, 'Carmen Diaz');
-      // un-included to-many relationship is simply absent, not [] or null
+      assertFalse('type' in data);
+      // WART: un-included relationships are absent from the wire entirely,
+      // so the hydrator cannot emit [] or null for them without a resource
+      // descriptor (arity is not on the wire)
       assertEquals(data.comments, undefined);
     },
   );
@@ -157,10 +162,10 @@ Deno.test('hydration', async (t) => {
   await t.step(
     'nested include hydrates to NOTHING because linkage is missing',
     async () => {
-      const { doc } = await getDoc('articles/3?include=comments.author');
-      const { data } = hydrateResponse<ContractArticle>(
-        doc as JsonApiSingleResponse,
+      const { doc } = await getDoc<Single>(
+        'articles/3?include=comments.author',
       );
+      const { data } = hydrateResponse<ContractArticle>(doc);
       // included has 4 resources, but without data.relationships the
       // hydrator cannot attach any of them
       assertEquals(data.comments, undefined);
@@ -168,14 +173,13 @@ Deno.test('hydration', async (t) => {
     },
   );
 
-  await t.step('collection hydration preserves meta and links', async () => {
-    const { doc } = await getDoc('articles?include=author&page%5Bsize%5D=2');
-    const { data, meta, links } = hydrateResponse<ContractArticle>(
-      doc as JsonApiArrayResponse,
+  await t.step('collection hydration returns data and pagination', async () => {
+    const { doc } = await getDoc<List>(
+      'articles?include=author&page%5Bsize%5D=2',
     );
+    const { data, pagination } = hydrateResponse<ContractArticle>(doc);
     assertEquals(data.length, 2);
     assertEquals(data[0].author.name, 'Astrid Berg');
-    assertEquals(meta?.pagination?.totalResources, 25);
-    assert(links?.self);
+    assertEquals(pagination?.totalResources, 25);
   });
 });
diff --git a/clients/typescript/contract/errors_contract_test.ts b/clients/typescript/contract/errors_contract_test.ts
index 91cdf3a..be6008b 100644
--- a/clients/typescript/contract/errors_contract_test.ts
+++ b/clients/typescript/contract/errors_contract_test.ts
@@ -4,11 +4,11 @@
  */
 import { assert, assertEquals, assertFalse } from '@std/assert';
 import { isJsonApiErrorResponse } from '../src/index.ts';
-import { getDoc, request } from './helpers.ts';
+import { type Errors, getDoc, type List, request } from './helpers.ts';
 
 Deno.test('not found', async (t) => {
   await t.step('WART: plain GET 404 has no error code', async () => {
-    const { doc, status } = await getDoc('articles/999');
+    const { doc, status } = await getDoc<Errors>('articles/999');
     assertEquals(status, 404);
     assertEquals(doc.errors, [
       { status: '404', title: 'Not Found', detail: 'Resource not found' },
@@ -19,7 +19,7 @@ Deno.test('not found', async (t) => {
   await t.step(
     'explicit JsonApiErrors.NotFound carries RESOURCE_NOT_FOUND and meta',
     async () => {
-      const { doc, status } = await request('DELETE', 'articles/999');
+      const { doc, status } = await request<Errors>('DELETE', 'articles/999');
       assertEquals(status, 404);
       assertEquals(doc.errors[0].code, 'RESOURCE_NOT_FOUND');
       assertEquals(doc.errors[0].meta, { resourceType: 'articles', id: 999 });
@@ -31,7 +31,7 @@ Deno.test('include allowlisting', async (t) => {
   await t.step(
     'unlisted include is 403 INCLUDE_NOT_ALLOWED with meta',
     async () => {
-      const { doc, status } = await getDoc('articles/3?include=bogus');
+      const { doc, status } = await getDoc<Errors>('articles/3?include=bogus');
       assertEquals(status, 403);
       assertEquals(doc.errors[0].code, 'INCLUDE_NOT_ALLOWED');
       assertEquals(doc.errors[0].meta, {
@@ -43,10 +43,10 @@ Deno.test('include allowlisting', async (t) => {
   );
 
   await t.step('empty [AllowedIncludes] forbids every include', async () => {
-    const { doc, status } = await getDoc('authors?include=articles');
+    const { doc, status } = await getDoc<Errors>('authors?include=articles');
     assertEquals(status, 403);
     assertEquals(doc.errors[0].code, 'INCLUDE_NOT_ALLOWED');
-    assertEquals(doc.errors[0].meta.allowedIncludes, []);
+    assertEquals(doc.errors[0].meta?.allowedIncludes, []);
   });
 
   await t.step(
@@ -54,19 +54,19 @@ Deno.test('include allowlisting', async (t) => {
     async () => {
       // filter[or][field][op] parses as an include-filter on a relationship
       // named "or", which a non-empty allowlist then rejects
-      const { doc, status } = await getDoc(
+      const { doc, status } = await getDoc<Errors>(
         'articles/3?filter%5Bor%5D%5BviewCount%5D%5Bgt%5D=230',
       );
       assertEquals(status, 403);
       assertEquals(doc.errors[0].code, 'FILTER_NOT_ALLOWED');
-      assertEquals(doc.errors[0].meta.forbiddenFilterPaths, ['or']);
+      assertEquals(doc.errors[0].meta?.forbiddenFilterPaths, ['or']);
     },
   );
 
   await t.step(
     'indexed (builder-emitted) groups pass the allowlist and apply',
     async () => {
-      const { doc, status } = await getDoc(
+      const { doc, status } = await getDoc<List>(
         'authors?filter%5Bor%5D%5B0%5D%5Bname%5D=x',
       );
       assertEquals(status, 200);
@@ -108,7 +108,7 @@ Deno.test('server errors', async (t) => {
   await t.step(
     'WART: unconvertible filter values are 500, not 400',
     async () => {
-      const { doc, status } = await getDoc(
+      const { doc, status } = await getDoc<Errors>(
         'articles?filter%5BpublishedAt%5D=isnull',
       );
       assertEquals(status, 500);
diff --git a/clients/typescript/contract/helpers.ts b/clients/typescript/contract/helpers.ts
index 3d3007c..25f1f7f 100644
--- a/clients/typescript/contract/helpers.ts
+++ b/clients/typescript/contract/helpers.ts
@@ -1,4 +1,3 @@
-// deno-lint-ignore-file no-explicit-any
 /**
  * Shared plumbing for the contract test suite.
  *
@@ -6,6 +5,11 @@
  * wire behavior, warts included. It assumes a freshly seeded server (see
  * samples/ContractApi/Data.cs); restart the sample between local runs.
  */
+import type {
+  JsonApiArrayResponse,
+  JsonApiErrorResponse,
+  JsonApiSingleResponse,
+} from '../src/index.ts';
 
 export const BASE_URL = Deno.env.get('CONTRACT_API_URL') ??
   'http://localhost:5198';
@@ -17,6 +21,11 @@ export const TOTAL_ARTICLES = 25;
 export const PUBLISHED_ARTICLES = 13; // odd ids 1..25
 export const UNPUBLISHED_ARTICLES = 12; // even ids, publishedAt is null
 
+/** Wire document shapes, named short because every test step names one. */
+export type Single = JsonApiSingleResponse;
+export type List = JsonApiArrayResponse;
+export type Errors = JsonApiErrorResponse;
+
 /**
  * Resource types as today's consumers write them: non-nullable everywhere,
  * because the current AttributeKeys/RelationshipKeys helpers drop nullable
@@ -50,17 +59,22 @@ export type ContractArticle = {
   comments: ContractComment[];
 };
 
-export interface WireResult {
+export interface WireResult<T> {
   status: number;
-  doc: any;
+  /** Parsed JSON body as `T`; `null` when the body is empty or not JSON. */
+  doc: T;
   headers: Headers;
 }
 
-export async function request(
+/**
+ * Raw request. `T` is the caller's claim about the body shape; the suite
+ * asserts on the wire, so a wrong claim fails loudly at the assertion.
+ */
+export async function request<T = unknown>(
   method: string,
   path: string,
   opts: { body?: unknown; contentType?: string; base?: string } = {},
-): Promise<WireResult> {
+): Promise<WireResult<T>> {
   const res = await fetch(`${opts.base ?? BASE_URL}/${path}`, {
     method,
     headers: opts.body !== undefined
@@ -69,7 +83,7 @@ export async function request(
     body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
   });
   const text = await res.text();
-  let doc: any = null;
+  let doc: unknown = null;
   if (text) {
     try {
       doc = JSON.parse(text);
@@ -77,14 +91,17 @@ export async function request(
       doc = text;
     }
   }
-  return { status: res.status, doc, headers: res.headers };
+  return { status: res.status, doc: doc as T, headers: res.headers };
 }
 
-export function getDoc(path: string, base?: string): Promise<WireResult> {
-  return request('GET', path, { base });
+export function getDoc<T = unknown>(
+  path: string,
+  base?: string,
+): Promise<WireResult<T>> {
+  return request<T>('GET', path, { base });
 }
 
 /** Convenience: totalResources from a collection response. */
-export function total(doc: any): number {
-  return doc?.meta?.pagination?.totalResources;
+export function total(doc: List): number | undefined {
+  return doc.meta?.pagination?.totalResources;
 }
diff --git a/clients/typescript/contract/pagination_contract_test.ts b/clients/typescript/contract/pagination_contract_test.ts
index 61f256c..fc188ce 100644
--- a/clients/typescript/contract/pagination_contract_test.ts
+++ b/clients/typescript/contract/pagination_contract_test.ts
@@ -5,7 +5,9 @@
 import { assert, assertEquals, assertFalse } from '@std/assert';
 import {
   BASE_URL,
+  type Errors,
   getDoc,
+  type List,
   PUBLISHED_ARTICLES,
   STRICT_BASE_URL,
   total,
@@ -16,19 +18,19 @@ Deno.test('default pagination', async (t) => {
   await t.step(
     'WART: no page params returns the entire collection, unpaginated',
     async () => {
-      const { doc } = await getDoc('articles');
+      const { doc } = await getDoc<List>('articles');
       assertEquals(doc.data.length, TOTAL_ARTICLES);
       assertEquals(doc.meta, undefined); // no pagination meta at all
-      assertEquals(Object.keys(doc.links), ['self']); // no first/last/next
+      assertEquals(Object.keys(doc.links ?? {}), ['self']); // no first/last/next
     },
   );
 
   await t.step(
     'any page param triggers pagination with DefaultPageSize 10',
     async () => {
-      const { doc } = await getDoc('articles?page%5Bnumber%5D=1');
+      const { doc } = await getDoc<List>('articles?page%5Bnumber%5D=1');
       assertEquals(doc.data.length, 10);
-      assertEquals(doc.meta.pagination, {
+      assertEquals(doc.meta?.pagination, {
         totalResources: TOTAL_ARTICLES,
         totalPages: 3,
         currentPage: 1,
@@ -38,18 +40,20 @@ Deno.test('default pagination', async (t) => {
   );
 
   await t.step('WART: page 0 and negative pages clamp to page 1', async () => {
-    const { doc } = await getDoc('articles?page%5Bnumber%5D=0');
-    assertEquals(doc.meta.pagination.currentPage, 1);
-    const { doc: neg } = await getDoc('articles?page%5Bnumber%5D=-5');
-    assertEquals(neg.meta.pagination.currentPage, 1);
+    const { doc } = await getDoc<List>('articles?page%5Bnumber%5D=0');
+    assertEquals(doc.meta?.pagination?.currentPage, 1);
+    const { doc: neg } = await getDoc<List>('articles?page%5Bnumber%5D=-5');
+    assertEquals(neg.meta?.pagination?.currentPage, 1);
   });
 
   await t.step(
     'WART: overflowing page numbers clamp to the last page',
     async () => {
-      const { doc, status } = await getDoc('articles?page%5Bnumber%5D=999');
+      const { doc, status } = await getDoc<List>(
+        'articles?page%5Bnumber%5D=999',
+      );
       assertEquals(status, 200);
-      assertEquals(doc.meta.pagination.currentPage, 3);
+      assertEquals(doc.meta?.pagination?.currentPage, 3);
       assertEquals(doc.data[0].id, '21');
     },
   );
@@ -57,8 +61,8 @@ Deno.test('default pagination', async (t) => {
   await t.step(
     'WART: oversized page size clamps to MaxPageSize (100)',
     async () => {
-      const { doc } = await getDoc('articles?page%5Bsize%5D=1000');
-      assertEquals(doc.meta.pagination.pageSize, 100);
+      const { doc } = await getDoc<List>('articles?page%5Bsize%5D=1000');
+      assertEquals(doc.meta?.pagination?.pageSize, 100);
     },
   );
 });
@@ -66,30 +70,30 @@ Deno.test('default pagination', async (t) => {
 Deno.test('pagination links', async (t) => {
   await t.step('self link preserves the full query string', async () => {
     const path = 'articles?filter%5Bpublished%5D=true&page%5Bsize%5D=2';
-    const { doc } = await getDoc(path);
-    assertEquals(doc.links.self, `${BASE_URL}/${path}`);
+    const { doc } = await getDoc<List>(path);
+    assertEquals(doc.links?.self, `${BASE_URL}/${path}`);
   });
 
   await t.step(
     'WART: first/last/prev/next drop filter, sort, include and fields',
     async () => {
-      const { doc } = await getDoc(
+      const { doc } = await getDoc<List>(
         'articles?filter%5Bpublished%5D=true&sort=-viewCount&page%5Bsize%5D=2',
       );
       // links are rebuilt from the bare path with unencoded brackets
       assertEquals(
-        doc.links.next,
+        doc.links?.next,
         `${BASE_URL}/articles?page[number]=2&page[size]=2`,
       );
       assertEquals(
-        doc.links.last,
+        doc.links?.last,
         `${BASE_URL}/articles?page[number]=7&page[size]=2`,
       );
-      assertFalse(doc.links.next.includes('filter'));
+      assertFalse(doc.links?.next?.includes('filter'));
 
       // following next therefore returns UNFILTERED, UNSORTED data
-      const next = new URL(doc.links.next);
-      const { doc: page2 } = await getDoc(`articles${next.search}`);
+      const next = new URL(doc.links?.next ?? '');
+      const { doc: page2 } = await getDoc<List>(`articles${next.search}`);
       assertEquals(total(page2), TOTAL_ARTICLES);
     },
   );
@@ -97,18 +101,18 @@ Deno.test('pagination links', async (t) => {
 
 Deno.test('strict pagination (StrictPagination = true)', async (t) => {
   await t.step('valid pages behave like default mode', async () => {
-    const { doc, status } = await getDoc(
+    const { doc, status } = await getDoc<List>(
       'articles?page%5Bnumber%5D=2',
       STRICT_BASE_URL,
     );
     assertEquals(status, 200);
-    assertEquals(doc.meta.pagination.currentPage, 2);
+    assertEquals(doc.meta?.pagination?.currentPage, 2);
   });
 
   await t.step(
     'overflowing page number is 404 INVALID_PAGE_NUMBER',
     async () => {
-      const { doc, status } = await getDoc(
+      const { doc, status } = await getDoc<Errors>(
         'articles?page%5Bnumber%5D=999',
         STRICT_BASE_URL,
       );
@@ -124,7 +128,7 @@ Deno.test('strict pagination (StrictPagination = true)', async (t) => {
   );
 
   await t.step('page 0 is 400 INVALID_PAGE_NUMBER (not clamped)', async () => {
-    const { doc, status } = await getDoc(
+    const { doc, status } = await getDoc<Errors>(
       'articles?page%5Bnumber%5D=0',
       STRICT_BASE_URL,
     );
@@ -135,13 +139,13 @@ Deno.test('strict pagination (StrictPagination = true)', async (t) => {
   await t.step(
     'oversized page size is 400 PAGE_SIZE_EXCEEDED (not clamped)',
     async () => {
-      const { doc, status } = await getDoc(
+      const { doc, status } = await getDoc<Errors>(
         'articles?page%5Bsize%5D=1000',
         STRICT_BASE_URL,
       );
       assertEquals(status, 400);
       assertEquals(doc.errors[0].code, 'PAGE_SIZE_EXCEEDED');
-      assert(doc.errors[0].meta.max === 100);
+      assert(doc.errors[0].meta?.max === 100);
     },
   );
 });
@@ -150,20 +154,20 @@ Deno.test(
   'pagination links with PreserveQueryInPaginationLinks (opt-in, strict instance)',
   async (t) => {
     await t.step('links keep the query, only page params change', async () => {
-      const { doc } = await getDoc(
+      const { doc } = await getDoc<List>(
         'articles?filter%5Bpublished%5D=true&sort=-viewCount&page%5Bsize%5D=2',
         STRICT_BASE_URL,
       );
       // keys are re-encoded by the link builder (%5B/%5D)
       assertEquals(
-        doc.links.next,
+        doc.links?.next,
         `${STRICT_BASE_URL}/articles` +
           '?filter%5Bpublished%5D=true&sort=-viewCount&page%5Bnumber%5D=2&page%5Bsize%5D=2',
       );
 
       // following next keeps the filtered, sorted result set
-      const next = new URL(doc.links.next);
-      const { doc: page2 } = await getDoc(
+      const next = new URL(doc.links?.next ?? '');
+      const { doc: page2 } = await getDoc<List>(
         `articles${next.search}`,
         STRICT_BASE_URL,
       );
diff --git a/clients/typescript/contract/query_contract_test.ts b/clients/typescript/contract/query_contract_test.ts
index 9e322dc..38b9e45 100644
--- a/clients/typescript/contract/query_contract_test.ts
+++ b/clients/typescript/contract/query_contract_test.ts
@@ -8,6 +8,7 @@ import { JsonApiQueryBuilder } from '../src/index.ts';
 import {
   type ContractArticle,
   getDoc,
+  type List,
   PUBLISHED_ARTICLES,
   total,
   TOTAL_ARTICLES,
@@ -15,7 +16,7 @@ import {
 } from './helpers.ts';
 
 function list(qb: JsonApiQueryBuilder<ContractArticle>) {
-  return getDoc(
+  return getDoc<List>(
     `articles?${qb.page(1, 1).fields('articles', ['title']).build()}`,
   );
 }
@@ -63,14 +64,10 @@ Deno.test('simple filters', async (t) => {
   });
 
   await t.step(
-    'isnull requires the 3-arg form with a dummy value',
+    'filterNull() emits filter[field][isnull]',
     async () => {
       const { doc } = await list(
-        new JsonApiQueryBuilder<ContractArticle>().filter(
-          'publishedAt',
-          'isnull',
-          true,
-        ),
+        new JsonApiQueryBuilder<ContractArticle>().filterNull('publishedAt'),
       );
       assertEquals(total(doc), UNPUBLISHED_ARTICLES);
     },
@@ -79,7 +76,10 @@ Deno.test('simple filters', async (t) => {
   await t.step(
     'WART: 2-arg isnull serializes the operator as the value and blows up',
     async () => {
-      // filter[publishedAt]=isnull -> unconvertible DateTime -> 500
+      // filter[publishedAt]=isnull -> unconvertible DateTime -> 500.
+      // TypeScript cannot reject "isnull" here without also rejecting every
+      // other free-form string value passed to the 2-arg form; use
+      // filterNull() instead.
       const qb = new JsonApiQueryBuilder<ContractArticle>().filter(
         'publishedAt',
         'isnull',
@@ -91,21 +91,21 @@ Deno.test('simple filters', async (t) => {
   );
 
   await t.step(
-    'WART: Date values serialize via String(), not ISO, and blow up',
+    'a Date value serializes to ISO 8601 and works, same as an ISO string',
     async () => {
-      const qb = new JsonApiQueryBuilder<ContractArticle>().filter(
-        'publishedAt',
-        'gt',
-        new Date('2025-01-20T00:00:00Z'),
+      const { doc } = await list(
+        new JsonApiQueryBuilder<ContractArticle>().filter(
+          'publishedAt',
+          'gt',
+          new Date('2025-01-20T00:00:00Z'),
+        ),
       );
-      assertEquals(qb.build().includes('2025-01-20T00'), false);
-      const { status } = await getDoc(`articles?${qb.build()}`);
-      assertEquals(status, 500);
+      assertEquals(total(doc), 3); // articles 21, 23, 25, same as the ISO-string test above
     },
   );
 
   await t.step('WART: unknown filter fields are silently ignored', async () => {
-    const { doc, status } = await getDoc(
+    const { doc, status } = await getDoc<List>(
       'articles?filter%5Bbogus%5D=x&page%5Bsize%5D=1',
     );
     assertEquals(status, 200);
@@ -136,11 +136,15 @@ Deno.test('filter groups', async (t) => {
   await t.step(
     'WART: and group serializes to filter[and] and is silently dropped',
     async () => {
-      const { doc, status } = await list(
-        new JsonApiQueryBuilder<ContractArticle>().and((b) =>
-          b.filter('published', 'eq', false)
-        ),
-      );
+      // The builder can no longer construct filter[and] at all (removed,
+      // see DESIGN.md); hand-build the wire shape to prove the backend
+      // still silently drops it if some other caller sends it.
+      const params = new URLSearchParams({
+        'filter[and][0][published]': 'false',
+        'page[size]': '1',
+        'fields[articles]': 'title',
+      });
+      const { doc, status } = await getDoc<List>(`articles?${params}`);
       assertEquals(status, 200);
       assertEquals(total(doc), TOTAL_ARTICLES); // filter had no effect
     },
@@ -149,13 +153,16 @@ Deno.test('filter groups', async (t) => {
   await t.step(
     'WART: nested groups are silently dropped, siblings still apply',
     async () => {
-      const { doc } = await list(
-        new JsonApiQueryBuilder<ContractArticle>().or((b) =>
-          b.filter('title', 'eq', 'Article 01').and((bb) =>
-            bb.filter('published', 'eq', true)
-          )
-        ),
-      );
+      // The builder can no longer construct nesting at all (compile error,
+      // see DESIGN.md); hand-build the wire shape to prove the backend
+      // still silently drops it if some other caller sends it.
+      const params = new URLSearchParams({
+        'filter[or][0][title]': 'Article 01',
+        'filter[or][1][and][0][published]': 'true',
+        'page[size]': '1',
+        'fields[articles]': 'title',
+      });
+      const { doc } = await getDoc<List>(`articles?${params}`);
       // nested and-branch vanishes; only title=Article 01 remains in the OR
       assertEquals(total(doc), 1);
     },
@@ -171,9 +178,9 @@ Deno.test('dot-path filters', async (t) => {
         .include('author')
         .page(1, 1)
         .build();
-      const { doc } = await getDoc(`articles?${qs}`);
+      const { doc } = await getDoc<List>(`articles?${qs}`);
       assertEquals(total(doc), 9); // seed: authors round-robin, Astrid owns 9
-      assertEquals(doc.included[0].attributes.name, 'Astrid Berg');
+      assertEquals(doc.included?.[0].attributes.name, 'Astrid Berg');
     },
   );
 
@@ -187,6 +194,57 @@ Deno.test('dot-path filters', async (t) => {
     );
     assertEquals(total(doc), 9);
   });
+
+  await t.step(
+    'deep dot-path filter through a to-many relationship (Any())',
+    async () => {
+      // "comments.author.name": articles.comments (to-many) .author (to-one)
+      // .name. Two dots, only reachable through the type's escape hatch
+      // (DeepAttributeKeys) since it goes through a to-many relationship.
+      const { doc } = await list(
+        new JsonApiQueryBuilder<ContractArticle>().filter(
+          'comments.author.name',
+          'like',
+          'Astrid',
+        ),
+      );
+      assertEquals(total(doc), 7); // seed: 7 articles have a comment by Astrid
+    },
+  );
+});
+
+Deno.test('included-relationship filters (filterIncluded)', async (t) => {
+  await t.step(
+    "trims a to-many relationship's included entries, primary resources unaffected",
+    async () => {
+      const qs = new JsonApiQueryBuilder<ContractArticle>()
+        .filterIncluded('comments', 'text', 'like', 'Comment 1')
+        .include('comments')
+        .page(1, 3)
+        .build();
+      const { doc } = await getDoc<List>(`articles?${qs}`);
+      assertEquals(total(doc), TOTAL_ARTICLES); // filter never touches `data`
+      const texts = doc.included?.map((r) => r.attributes.text);
+      assertEquals(texts?.length, 3); // one matching comment per article
+      assertEquals(texts?.every((t) => String(t).includes('Comment 1')), true);
+    },
+  );
+
+  await t.step(
+    'WART: filterIncluded() on a to-one relationship has no effect',
+    async () => {
+      const qs = new JsonApiQueryBuilder<ContractArticle>()
+        .filterIncluded('author', 'name', 'like', 'Astrid')
+        .include('author')
+        .page(1, 3)
+        .build();
+      const { doc } = await getDoc<List>(`articles?${qs}`);
+      const names = new Set(doc.included?.map((r) => r.attributes.name));
+      // every author still comes back, not just Astrid's; EF's filtered
+      // include only applies to collection navigations, not to-one refs.
+      assertEquals(names.size > 1, true);
+    },
+  );
 });
 
 Deno.test('sorting', async (t) => {
@@ -209,11 +267,18 @@ Deno.test('sorting', async (t) => {
   });
 
   await t.step(
-    'WART: dot-path sort compiles in the builder but is silently ignored',
+    'WART: dot-path sort is silently ignored',
     async () => {
-      const { doc, status } = await list(
-        new JsonApiQueryBuilder<ContractArticle>().sort('author.name'),
-      );
+      // The builder can no longer construct this at all (sort() is
+      // restricted to DirectAttributeKeys<T>, see DESIGN.md); hand-build
+      // the wire shape to prove the backend still silently ignores it if
+      // some other caller sends it.
+      const params = new URLSearchParams({
+        sort: 'author.name',
+        'page[size]': '1',
+        'fields[articles]': 'title',
+      });
+      const { doc, status } = await getDoc<List>(`articles?${params}`);
       assertEquals(status, 200);
       assertEquals(doc.data[0].id, '1'); // insertion order, sort had no effect
     },
diff --git a/clients/typescript/contract/strict_contract_test.ts b/clients/typescript/contract/strict_contract_test.ts
index f4f2a4b..2a4da25 100644
--- a/clients/typescript/contract/strict_contract_test.ts
+++ b/clients/typescript/contract/strict_contract_test.ts
@@ -7,40 +7,45 @@ import { assertEquals } from '@std/assert';
 import { JsonApiQueryBuilder } from '../src/index.ts';
 import {
   type ContractArticle,
+  type Errors,
   getDoc,
+  type List,
   STRICT_BASE_URL,
   total,
 } from './helpers.ts';
 
-function strictGet(qs: string) {
-  return getDoc(`articles?${qs}`, STRICT_BASE_URL);
+function strictGet<T = unknown>(qs: string) {
+  return getDoc<T>(`articles?${qs}`, STRICT_BASE_URL);
 }
 
 Deno.test('strict query validation: rejected shapes', async (t) => {
   await t.step('and group is 400 UNSUPPORTED_FILTER_GROUP', async () => {
-    const qs = new JsonApiQueryBuilder<ContractArticle>()
-      .and((b) => b.filter('published', 'eq', false))
-      .build();
-    const { doc, status } = await strictGet(qs);
+    // The builder can no longer construct filter[and] at all (removed, see
+    // DESIGN.md); hand-build the wire shape to prove the backend still
+    // rejects it if some other caller sends it.
+    const qs = new URLSearchParams({
+      'filter[and][0][published]': 'false',
+    }).toString();
+    const { doc, status } = await strictGet<Errors>(qs);
     assertEquals(status, 400);
     assertEquals(doc.errors[0].code, 'UNSUPPORTED_FILTER_GROUP');
   });
 
   await t.step('nested group is 400 UNSUPPORTED_FILTER_GROUP', async () => {
-    const qs = new JsonApiQueryBuilder<ContractArticle>()
-      .or((b) =>
-        b.filter('title', 'eq', 'Article 01').and((bb) =>
-          bb.filter('published', 'eq', true)
-        )
-      )
-      .build();
-    const { doc, status } = await strictGet(qs);
+    // The builder can no longer construct nesting at all (compile error,
+    // see DESIGN.md); hand-build the wire shape to prove the backend still
+    // rejects it if some other caller sends it.
+    const qs = new URLSearchParams({
+      'filter[or][0][title]': 'Article 01',
+      'filter[or][1][and][0][published]': 'true',
+    }).toString();
+    const { doc, status } = await strictGet<Errors>(qs);
     assertEquals(status, 400);
     assertEquals(doc.errors[0].code, 'UNSUPPORTED_FILTER_GROUP');
   });
 
   await t.step('unknown filter field is 400 INVALID_FILTER_FIELD', async () => {
-    const { doc, status } = await strictGet('filter%5Bbogus%5D=x');
+    const { doc, status } = await strictGet<Errors>('filter%5Bbogus%5D=x');
     assertEquals(status, 400);
     assertEquals(doc.errors[0].code, 'INVALID_FILTER_FIELD');
   });
@@ -51,26 +56,14 @@ Deno.test('strict query validation: rejected shapes', async (t) => {
       const qs = new JsonApiQueryBuilder<ContractArticle>()
         .filter('publishedAt', 'isnull')
         .build();
-      const { doc, status } = await strictGet(qs);
-      assertEquals(status, 400);
-      assertEquals(doc.errors[0].code, 'INVALID_FILTER_VALUE');
-    },
-  );
-
-  await t.step(
-    'Date value wart is 400 INVALID_FILTER_VALUE, not 500',
-    async () => {
-      const qs = new JsonApiQueryBuilder<ContractArticle>()
-        .filter('publishedAt', 'gt', new Date('2025-01-20T00:00:00Z'))
-        .build();
-      const { doc, status } = await strictGet(qs);
+      const { doc, status } = await strictGet<Errors>(qs);
       assertEquals(status, 400);
       assertEquals(doc.errors[0].code, 'INVALID_FILTER_VALUE');
     },
   );
 
   await t.step('unknown operator is 400 INVALID_FILTER_OPERATOR', async () => {
-    const { doc, status } = await strictGet(
+    const { doc, status } = await strictGet<Errors>(
       'filter%5Btitle%5D%5Bcontains%5D=x',
     );
     assertEquals(status, 400);
@@ -78,16 +71,18 @@ Deno.test('strict query validation: rejected shapes', async (t) => {
   });
 
   await t.step('unknown sort field is 400 INVALID_SORT_FIELD', async () => {
-    const { doc, status } = await strictGet('sort=bogus');
+    const { doc, status } = await strictGet<Errors>('sort=bogus');
     assertEquals(status, 400);
     assertEquals(doc.errors[0].code, 'INVALID_SORT_FIELD');
   });
 
   await t.step('dot-path sort is 400 INVALID_SORT_FIELD', async () => {
-    const qs = new JsonApiQueryBuilder<ContractArticle>()
-      .sort('author.name')
-      .build();
-    const { doc, status } = await strictGet(qs);
+    // The builder can no longer construct this at all (sort() is
+    // restricted to DirectAttributeKeys<T>, see DESIGN.md); hand-build the
+    // wire shape to prove the backend still rejects it if some other
+    // caller sends it.
+    const qs = new URLSearchParams({ sort: 'author.name' }).toString();
+    const { doc, status } = await strictGet<Errors>(qs);
     assertEquals(status, 400);
     assertEquals(doc.errors[0].code, 'INVALID_SORT_FIELD');
   });
@@ -95,7 +90,7 @@ Deno.test('strict query validation: rejected shapes', async (t) => {
   await t.step(
     'bracket include-filter without include is 400 FILTER_NOT_ALLOWED',
     async () => {
-      const { doc, status } = await strictGet(
+      const { doc, status } = await strictGet<Errors>(
         'filter%5Bauthor%5D%5Bname%5D%5Blike%5D=Astrid',
       );
       assertEquals(status, 400);
@@ -114,16 +109,26 @@ Deno.test('strict query validation: valid queries unaffected', async (t) => {
       .include('author')
       .page(1, 10)
       .build();
-    const { doc, status } = await strictGet(qs);
+    const { doc, status } = await strictGet<List>(qs);
     assertEquals(status, 200);
     assertEquals(total(doc), 3);
     assertEquals(doc.data[0].id, '25');
 
     const isnull = new JsonApiQueryBuilder<ContractArticle>()
-      .filter('publishedAt', 'isnull', true)
+      .filterNull('publishedAt')
       .page(1, 1)
       .build();
-    const { doc: nulls } = await strictGet(isnull);
+    const { doc: nulls } = await strictGet<List>(isnull);
     assertEquals(total(nulls), 12);
   });
+
+  await t.step('a Date filter value (ISO 8601) still works', async () => {
+    const qs = new JsonApiQueryBuilder<ContractArticle>()
+      .filter('publishedAt', 'gt', new Date('2025-01-20T00:00:00Z'))
+      .page(1, 1)
+      .build();
+    const { doc, status } = await strictGet<List>(qs);
+    assertEquals(status, 200);
+    assertEquals(total(doc), 3); // articles 21, 23, 25
+  });
 });
diff --git a/clients/typescript/contract/writes_contract_test.ts b/clients/typescript/contract/writes_contract_test.ts
index 360fc49..1399e9f 100644
--- a/clients/typescript/contract/writes_contract_test.ts
+++ b/clients/typescript/contract/writes_contract_test.ts
@@ -7,7 +7,7 @@
  * contract keeps seeing the pristine seed.
  */
 import { assert, assertEquals } from '@std/assert';
-import { getDoc, request } from './helpers.ts';
+import { type Errors, getDoc, request, type Single } from './helpers.ts';
 
 Deno.test('write path', async (t) => {
   let createdId = '';
@@ -15,16 +15,20 @@ Deno.test('write path', async (t) => {
   await t.step(
     'POST plain DTO returns 201 + Location + JSON:API document',
     async () => {
-      const { doc, status, headers } = await request('POST', 'articles', {
-        body: {
-          title: 'Contract test article',
-          body: 'Written by the contract suite',
-          published: true,
-          publishedAt: '2025-03-01T09:00:00Z',
-          authorId: 2,
-          tags: ['contract'],
+      const { doc, status, headers } = await request<Single>(
+        'POST',
+        'articles',
+        {
+          body: {
+            title: 'Contract test article',
+            body: 'Written by the contract suite',
+            published: true,
+            publishedAt: '2025-03-01T09:00:00Z',
+            authorId: 2,
+            tags: ['contract'],
+          },
         },
-      });
+      );
       assertEquals(status, 201);
       createdId = doc.data.id;
       assert(headers.get('location')?.endsWith(`/articles/${createdId}`));
@@ -39,7 +43,7 @@ Deno.test('write path', async (t) => {
   await t.step(
     'POST without required field is 400 REQUIRED_FIELD_MISSING',
     async () => {
-      const { doc, status } = await request('POST', 'articles', {
+      const { doc, status } = await request<Errors>('POST', 'articles', {
         body: { body: 'no title here' },
       });
       assertEquals(status, 400);
@@ -52,9 +56,13 @@ Deno.test('write path', async (t) => {
   await t.step(
     'PATCH applies partial updates, other fields untouched',
     async () => {
-      const { doc, status } = await request('PATCH', `articles/${createdId}`, {
-        body: { viewCount: 5 },
-      });
+      const { doc, status } = await request<Single>(
+        'PATCH',
+        `articles/${createdId}`,
+        {
+          body: { viewCount: 5 },
+        },
+      );
       assertEquals(status, 200);
       assertEquals(doc.data.attributes.viewCount, 5);
       assertEquals(doc.data.attributes.title, 'Contract test article');
@@ -65,9 +73,13 @@ Deno.test('write path', async (t) => {
   await t.step(
     'PATCH on a missing resource is 404 RESOURCE_NOT_FOUND',
     async () => {
-      const { doc, status } = await request('PATCH', 'articles/999999', {
-        body: { title: 'nope' },
-      });
+      const { doc, status } = await request<Errors>(
+        'PATCH',
+        'articles/999999',
+        {
+          body: { title: 'nope' },
+        },
+      );
       assertEquals(status, 404);
       assertEquals(doc.errors[0].code, 'RESOURCE_NOT_FOUND');
     },
diff --git a/clients/typescript/deno.json b/clients/typescript/deno.json
index f3b86cd..5b9a310 100644
--- a/clients/typescript/deno.json
+++ b/clients/typescript/deno.json
@@ -1,10 +1,21 @@
 {
-  "name": "@intility/jsonapi-ts-tools",
-  "publishConfig": {
-    "registry": "https://npm.pkg.github.com/"
-  },
+  "name": "@intility/json-api-client",
   "version": "0.6.0",
-  "exports": "./index.js",
+  "description": "TypeScript tools for JSON:API: response hydration, a type-safe query builder, and error types for JsonApiToolkit backends.",
+  "license": "MIT",
+  "exports": "./src/index.ts",
+  "publish": {
+    "exclude": [
+      "contract/",
+      "dist/",
+      "build_npm.ts",
+      "CLAUDE.md",
+      "CODEOWNERS",
+      "CHANGELOG.md",
+      "deno.lock",
+      "**/*_test.ts"
+    ]
+  },
   "tasks": {
     "check": "deno check src/**/*.ts contract/**/*.ts",
     "lint": "deno lint --ignore=README.md,.github/,CLAUDE.md,CODEOWNERS,CHANGELOG.md",
diff --git a/clients/typescript/src/client.ts b/clients/typescript/src/client.ts
new file mode 100644
index 0000000..fcbfd88
--- /dev/null
+++ b/clients/typescript/src/client.ts
@@ -0,0 +1,176 @@
+import type {
+  HydratedList,
+  JsonApiArrayResponse,
+  JsonApiResourceDescriptor,
+  JsonApiResourceDescriptorBase,
+  JsonApiResourceDescriptors,
+  JsonApiSingleResponse,
+} from './types/jsonapi.ts';
+import { hydrateResponse } from './hydrate.ts';
+import { isJsonApiErrorResponse, JsonApiRequestError } from './errors.ts';
+import { JsonApiQueryBuilder } from './query-builder/JsonApiQueryBuilder.ts';
+
+const JSON_API_CONTENT_TYPE = 'application/vnd.api+json';
+
+export interface JsonApiClientOptions {
+  /** Origin + path prefix, no trailing slash required (e.g. "https://api.example.com"). */
+  baseUrl: string;
+  /**
+   * Standard fetch signature. Attach auth (tokens, dynamic headers) in a
+   * wrapper and pass it here; the client owns content-type headers, status
+   * handling, and parsing. Defaults to the global `fetch`.
+   */
+  fetch?: typeof fetch;
+  /**
+   * Generated descriptors for resources that show up as `included` but
+   * never get their own handle. Descriptors passed to `resource()` are
+   * registered automatically.
+   */
+  resources?: readonly JsonApiResourceDescriptorBase[];
+}
+
+/** Pre-built query string, for interop with externally-built params (e.g. gjallarbru). */
+export interface RawQueryParams {
+  params: string;
+}
+
+export type QueryFn<T> = (builder: JsonApiQueryBuilder<T>) => unknown;
+
+/**
+ * Typed handle for one resource path. Bodies for `post`/`patch` are plain
+ * camelCase DTOs (the backend has no JSON:API request deserializer);
+ * responses are JSON:API documents, hydrated into plain objects.
+ */
+export interface JsonApiResourceHandle<T> {
+  /** Collection path relative to `baseUrl`, without slashes at either end. */
+  readonly path: string;
+  /**
+   * Serializes a query without sending it. Lets adapters build cache keys
+   * from the same string `list`/`get` send when given `{ params }`.
+   */
+  params(query?: QueryFn<T>): string;
+  list(query?: QueryFn<T> | RawQueryParams): Promise<HydratedList<T>>;
+  get(id: string | number, query?: QueryFn<T> | RawQueryParams): Promise<T>;
+  post(body: unknown): Promise<T>;
+  patch(id: string | number, body: unknown): Promise<T>;
+  /** 204 No Content on success. */
+  delete(id: string | number): Promise<void>;
+}
+
+export interface JsonApiClient {
+  /**
+   * Handle for a generated resource. `T` is inferred from the descriptor;
+   * hydration fills what the wire omits (see {@link JsonApiResourceDescriptor}).
+   * @param path Collection path relative to `baseUrl`; defaults to the wire type.
+   */
+  resource<T>(
+    descriptor: JsonApiResourceDescriptor<T>,
+    path?: string,
+  ): JsonApiResourceHandle<T>;
+  /**
+   * Handle for a hand-typed resource. No descriptor, so absent attributes
+   * and un-included relationships stay `undefined`.
+   * @param path Collection path relative to `baseUrl`, e.g. "articles".
+   */
+  resource<T>(path: string): JsonApiResourceHandle<T>;
+}
+
+function queryString<T>(query?: QueryFn<T> | RawQueryParams): string {
+  if (!query) return '';
+  if (typeof query === 'function') {
+    const builder = new JsonApiQueryBuilder<T>();
+    query(builder);
+    return builder.build();
+  }
+  return query.params;
+}
+
+async function readBody(res: Response): Promise<unknown> {
+  if (res.status === 204) return null;
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds a JSON:API client. `client.resource<T>(path)` returns a typed
+ * handle covering query building, fetch, hydration, and error handling for
+ * reads and writes in one call path.
+ *
+ * Any non-2xx response throws {@link JsonApiRequestError}.
+ */
+export function createJsonApiClient(
+  options: JsonApiClientOptions,
+): JsonApiClient {
+  const fetchImpl = options.fetch ?? fetch;
+  const baseUrl = options.baseUrl.replace(/\/+$/, '');
+  const descriptors: JsonApiResourceDescriptors = {};
+  for (const d of options.resources ?? []) descriptors[d.type] = d;
+
+  async function send(
+    method: string,
+    path: string,
+    opts: { qs?: string; body?: unknown } = {},
+  ): Promise<unknown> {
+    const url = opts.qs
+      ? `${baseUrl}/${path}?${opts.qs}`
+      : `${baseUrl}/${path}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: opts.body !== undefined
+        ? { 'Content-Type': JSON_API_CONTENT_TYPE }
+        : undefined,
+      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+    const doc = await readBody(res);
+    if (!res.ok) {
+      throw new JsonApiRequestError(
+        res.status,
+        isJsonApiErrorResponse(doc) ? doc.errors : [],
+      );
+    }
+    return doc;
+  }
+
+  function single<T>(doc: unknown): T {
+    return hydrateResponse<T>(doc as JsonApiSingleResponse, descriptors).data;
+  }
+
+  return {
+    resource<T>(
+      source: JsonApiResourceDescriptor<T> | string,
+      path?: string,
+    ): JsonApiResourceHandle<T> {
+      if (typeof source !== 'string') descriptors[source.type] = source;
+      const cleanPath =
+        (path ?? (typeof source === 'string' ? source : source.type))
+          .replace(/^\/+|\/+$/g, '');
+      return {
+        path: cleanPath,
+        params: queryString,
+        async list(query) {
+          const doc = await send('GET', cleanPath, { qs: queryString(query) });
+          return hydrateResponse<T>(doc as JsonApiArrayResponse, descriptors);
+        },
+        async get(id, query) {
+          return single<T>(
+            await send('GET', `${cleanPath}/${id}`, { qs: queryString(query) }),
+          );
+        },
+        async post(body) {
+          return single<T>(await send('POST', cleanPath, { body }));
+        },
+        async patch(id, body) {
+          return single<T>(await send('PATCH', `${cleanPath}/${id}`, { body }));
+        },
+        async delete(id) {
+          await send('DELETE', `${cleanPath}/${id}`);
+        },
+      };
+    },
+  };
+}
diff --git a/clients/typescript/src/client_test.ts b/clients/typescript/src/client_test.ts
new file mode 100644
index 0000000..f1dbb14
--- /dev/null
+++ b/clients/typescript/src/client_test.ts
@@ -0,0 +1,192 @@
+import { assertEquals, assertRejects } from '@std/assert';
+import { createJsonApiClient } from './client.ts';
+import { JsonApiRequestError } from './errors.ts';
+import type { JsonApiResourceDescriptor } from './types/jsonapi.ts';
+
+type Todo = { id: string; title: string; completed: boolean };
+
+const todoDoc = {
+  id: '1',
+  type: 'todos',
+  attributes: { title: 'a', completed: false },
+};
+const hydratedTodo: Todo = { id: '1', title: 'a', completed: false };
+
+/** Records the request it received and returns a canned Response. */
+function fakeFetch(
+  response: () => Response,
+): { fetch: typeof fetch; lastRequest: () => Request } {
+  let last: Request;
+  return {
+    fetch: ((input: string | URL | Request, init?: RequestInit) => {
+      last = new Request(input, init);
+      return Promise.resolve(response());
+    }) as typeof fetch,
+    lastRequest: () => last,
+  };
+}
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/vnd.api+json' },
+  });
+}
+
+function setup(response: () => Response) {
+  const { fetch: f, lastRequest } = fakeFetch(response);
+  const client = createJsonApiClient({
+    baseUrl: 'https://api.test/',
+    fetch: f,
+  });
+  return { todos: client.resource<Todo>('/todos'), lastRequest };
+}
+
+Deno.test('list', async (t) => {
+  await t.step('builds the URL from baseUrl, path, and query', async () => {
+    const { todos, lastRequest } = setup(() => jsonResponse(200, { data: [] }));
+    await todos.list((q) => q.filter('completed', true));
+    assertEquals(
+      lastRequest().url,
+      'https://api.test/todos?filter%5Bcompleted%5D=true',
+    );
+    assertEquals(lastRequest().method, 'GET');
+  });
+
+  await t.step('accepts pre-built params for interop', async () => {
+    const { todos, lastRequest } = setup(() => jsonResponse(200, { data: [] }));
+    await todos.list({ params: 'page[number]=2' });
+    assertEquals(lastRequest().url, 'https://api.test/todos?page[number]=2');
+  });
+
+  await t.step('returns hydrated data and pagination', async () => {
+    const pagination = {
+      totalResources: 1,
+      totalPages: 1,
+      currentPage: 1,
+      pageSize: 10,
+    };
+    const { todos } = setup(() =>
+      jsonResponse(200, { data: [todoDoc], meta: { pagination } })
+    );
+    assertEquals(await todos.list(), { data: [hydratedTodo], pagination });
+  });
+
+  await t.step('throws JsonApiRequestError on non-2xx', async () => {
+    const { todos } = setup(() =>
+      jsonResponse(404, {
+        errors: [{ status: '404', code: 'RESOURCE_NOT_FOUND' }],
+      })
+    );
+    const error = await assertRejects(() => todos.list(), JsonApiRequestError);
+    assertEquals(error.status, 404);
+    assertEquals(error.hasCode('RESOURCE_NOT_FOUND'), true);
+  });
+
+  await t.step('non-JSON:API error body yields empty errors', async () => {
+    const { todos } = setup(() => new Response(null, { status: 415 }));
+    const error = await assertRejects(() => todos.list(), JsonApiRequestError);
+    assertEquals(error.status, 415);
+    assertEquals(error.errors, []);
+  });
+});
+
+Deno.test('resource(descriptor)', async (t) => {
+  await t.step('paths from the wire type and fills omissions', async () => {
+    type Article = { id: string; title: string; author: Todo | null };
+    const Article: JsonApiResourceDescriptor<Article> = {
+      type: 'articles',
+      attributes: ['title'],
+      toOne: ['author'],
+      toMany: [],
+    };
+    const { fetch: f, lastRequest } = fakeFetch(() =>
+      jsonResponse(200, {
+        data: { id: '1', type: 'articles', attributes: { title: 'A' } },
+      })
+    );
+    const client = createJsonApiClient({
+      baseUrl: 'https://api.test',
+      fetch: f,
+    });
+    const article = await client.resource(Article).get(1);
+    assertEquals(lastRequest().url, 'https://api.test/articles/1');
+    assertEquals(article, { id: '1', title: 'A', author: null });
+  });
+});
+
+Deno.test('get', async (t) => {
+  await t.step('appends the id and returns the resource', async () => {
+    const { todos, lastRequest } = setup(() =>
+      jsonResponse(200, { data: todoDoc })
+    );
+    const todo = await todos.get(1, (q) => q.include('owner' as never));
+    assertEquals(lastRequest().url, 'https://api.test/todos/1?include=owner');
+    assertEquals(todo, hydratedTodo);
+  });
+});
+
+Deno.test('writes', async (t) => {
+  await t.step(
+    'post sends a plain DTO with the JSON:API content type',
+    async () => {
+      const { todos, lastRequest } = setup(() =>
+        jsonResponse(201, { data: todoDoc })
+      );
+      const created = await todos.post({ title: 'a' });
+      const req = lastRequest();
+      assertEquals(req.method, 'POST');
+      assertEquals(req.url, 'https://api.test/todos');
+      assertEquals(req.headers.get('content-type'), 'application/vnd.api+json');
+      assertEquals(await req.json(), { title: 'a' });
+      assertEquals(created, hydratedTodo);
+    },
+  );
+
+  await t.step('patch hits the id path with a partial DTO', async () => {
+    const { todos, lastRequest } = setup(() =>
+      jsonResponse(200, { data: todoDoc })
+    );
+    await todos.patch('1', { completed: true });
+    const req = lastRequest();
+    assertEquals(req.method, 'PATCH');
+    assertEquals(req.url, 'https://api.test/todos/1');
+    assertEquals(await req.json(), { completed: true });
+  });
+
+  await t.step('delete sends no body and resolves void on 204', async () => {
+    const { todos, lastRequest } = setup(() =>
+      new Response(null, { status: 204 })
+    );
+    assertEquals(await todos.delete(1), undefined);
+    assertEquals(lastRequest().method, 'DELETE');
+    assertEquals(lastRequest().url, 'https://api.test/todos/1');
+    assertEquals(lastRequest().headers.get('content-type'), null);
+  });
+});
+
+Deno.test('adapter surface', async (t) => {
+  await t.step('path is the cleaned collection path', () => {
+    const { todos } = setup(() => jsonResponse(200, { data: [] }));
+    assertEquals(todos.path, 'todos');
+  });
+
+  await t.step('params serializes without sending', () => {
+    const { todos, lastRequest } = setup(() => jsonResponse(200, { data: [] }));
+    const params = todos.params((q) => q.filter('completed', true).page(1, 20));
+    assertEquals(
+      params,
+      'filter%5Bcompleted%5D=true&page%5Bnumber%5D=1&page%5Bsize%5D=20',
+    );
+    assertEquals(lastRequest(), undefined);
+  });
+
+  await t.step('params round-trips through list and get', async () => {
+    const { todos, lastRequest } = setup(() =>
+      jsonResponse(200, { data: todoDoc })
+    );
+    const params = todos.params((q) => q.sort('title'));
+    await todos.get('1', { params });
+    assertEquals(lastRequest().url, `https://api.test/todos/1?${params}`);
+  });
+});
diff --git a/clients/typescript/src/errors.ts b/clients/typescript/src/errors.ts
index 51a45c4..0853844 100644
--- a/clients/typescript/src/errors.ts
+++ b/clients/typescript/src/errors.ts
@@ -1,4 +1,8 @@
-import type { JsonApiErrorResponse } from './types/errors.ts';
+import type {
+  JsonApiError,
+  JsonApiErrorCode,
+  JsonApiErrorResponse,
+} from './types/errors.ts';
 
 /**
  * Type guard that checks if a value is a JSON:API error response.
@@ -24,3 +28,40 @@ export function isJsonApiErrorResponse(
     Array.isArray((value as JsonApiErrorResponse).errors)
   );
 }
+
+/**
+ * Thrown by {@link createJsonApiClient} for any non-2xx response.
+ * `errors` is empty when the body was not a JSON:API error document
+ * (e.g. a 415 with no body).
+ */
+export class JsonApiRequestError extends Error {
+  readonly status: number;
+  readonly errors: JsonApiError[];
+
+  constructor(status: number, errors: JsonApiError[]) {
+    super(errors[0]?.title ?? `Request failed with status ${status}`);
+    this.name = 'JsonApiRequestError';
+    this.status = status;
+    this.errors = errors;
+  }
+
+  /** Whether any error in the response carries the given code. */
+  hasCode(code: JsonApiErrorCode): boolean {
+    return this.errors.some((error) => error.code === code);
+  }
+
+  /**
+   * Groups errors by the field named in `source.pointer`
+   * (e.g. "/data/attributes/email" -> "email"). Errors without a
+   * pointer are omitted.
+   */
+  fieldErrors(): Record<string, JsonApiError[]> {
+    const out: Record<string, JsonApiError[]> = {};
+    for (const error of this.errors) {
+      const field = error.source?.pointer?.split('/').pop();
+      if (!field) continue;
+      (out[field] ??= []).push(error);
+    }
+    return out;
+  }
+}
diff --git a/clients/typescript/src/errors_test.ts b/clients/typescript/src/errors_test.ts
index 8dd640f..03880c1 100644
--- a/clients/typescript/src/errors_test.ts
+++ b/clients/typescript/src/errors_test.ts
@@ -1,5 +1,5 @@
 import { assertEquals } from '@std/assert';
-import { isJsonApiErrorResponse } from './errors.ts';
+import { isJsonApiErrorResponse, JsonApiRequestError } from './errors.ts';
 import { JsonApiErrorCodes } from './types/errors.ts';
 
 Deno.test('isJsonApiErrorResponse', async (t) => {
@@ -109,3 +109,50 @@ Deno.test('JsonApiErrorCodes', async (t) => {
     assertEquals(Object.keys(JsonApiErrorCodes).length, 19);
   });
 });
+
+Deno.test('JsonApiRequestError', async (t) => {
+  await t.step('message falls back to the status when no errors', () => {
+    const error = new JsonApiRequestError(500, []);
+    assertEquals(error.message, 'Request failed with status 500');
+    assertEquals(error.status, 500);
+    assertEquals(error.errors, []);
+  });
+
+  await t.step('message uses the first error title', () => {
+    const error = new JsonApiRequestError(404, [
+      { status: '404', title: 'Not Found' },
+    ]);
+    assertEquals(error.message, 'Not Found');
+  });
+
+  await t.step('hasCode matches any error with that code', () => {
+    const error = new JsonApiRequestError(400, [
+      { code: JsonApiErrorCodes.VALIDATION_FAILED },
+      { code: JsonApiErrorCodes.REQUIRED_FIELD_MISSING },
+    ]);
+    assertEquals(error.hasCode(JsonApiErrorCodes.VALIDATION_FAILED), true);
+    assertEquals(error.hasCode(JsonApiErrorCodes.RESOURCE_NOT_FOUND), false);
+  });
+
+  await t.step("fieldErrors groups by the pointer's last segment", () => {
+    const error = new JsonApiRequestError(400, [
+      {
+        code: JsonApiErrorCodes.VALIDATION_FAILED,
+        source: { pointer: '/data/attributes/email' },
+      },
+      {
+        code: JsonApiErrorCodes.REQUIRED_FIELD_MISSING,
+        source: { pointer: '/data/attributes/email' },
+      },
+      {
+        code: JsonApiErrorCodes.REQUIRED_FIELD_MISSING,
+        source: { pointer: '/data/attributes/title' },
+      },
+      { code: JsonApiErrorCodes.AUTHENTICATION_REQUIRED }, // no pointer
+    ]);
+    const fields = error.fieldErrors();
+    assertEquals(Object.keys(fields).sort(), ['email', 'title']);
+    assertEquals(fields.email.length, 2);
+    assertEquals(fields.title.length, 1);
+  });
+});
diff --git a/clients/typescript/src/hydrate.ts b/clients/typescript/src/hydrate.ts
index f644988..e18004e 100644
--- a/clients/typescript/src/hydrate.ts
+++ b/clients/typescript/src/hydrate.ts
@@ -1,23 +1,16 @@
-// utils/hydrate.ts
-
 import type {
-  HydratedArrayResult,
-  HydratedSingleResult,
+  HydratedList,
+  HydratedSingle,
   JsonApiArrayResponse,
   JsonApiResource,
-  JsonApiResponse,
+  JsonApiResourceDescriptors,
   JsonApiSingleResponse,
 } from './types/jsonapi.ts';
 
-type ResourceMap = Record<string, Record<string, JsonApiResource>>;
+type IncludedMap = Record<string, Record<string, JsonApiResource>>;
 
-/**
- * Builds a lookup map for included resources.
- */
-function buildResourceMap(
-  included: JsonApiResource[] = [],
-): ResourceMap {
-  const map: ResourceMap = {};
+function buildIncludedMap(included: JsonApiResource[] = []): IncludedMap {
+  const map: IncludedMap = {};
   for (const res of included) {
     (map[res.type] ??= {})[res.id] = res;
   }
@@ -25,101 +18,80 @@ function buildResourceMap(
 }
 
 /**
- * Hydrates a single resource, resolving relationships.
+ * Flattens one resource: `{ id, ...attributes, ...relationships }`.
+ * Relationships resolve from `included`; a linked resource that is not
+ * included resolves to `null` (to-one) or is dropped (to-many). A cycle
+ * back to a resource already on the current path resolves to `null`.
+ *
+ * With a descriptor for the resource's wire type, what the wire omits is
+ * filled in: null-stripped attributes as `null`, un-included relationships
+ * as `null` (to-one) or `[]` (to-many).
  */
-function hydrateOne<T = unknown>(
+function hydrateOne<T>(
   resource: JsonApiResource,
-  map: ResourceMap,
-  deep: boolean,
-  visited: Set<string>,
+  map: IncludedMap,
+  descriptors: JsonApiResourceDescriptors,
+  path: Set<string>,
 ): T {
   const key = `${resource.type}:${resource.id}`;
-  if (visited.has(key)) {
-    // Prevent infinite recursion
-    return { id: resource.id, type: resource.type, circular: true } as T;
-  }
-  visited.add(key);
-
   const out: Record<string, unknown> = {
     id: resource.id,
-    type: resource.type,
     ...resource.attributes,
   };
+  const nextPath = new Set(path).add(key);
 
-  if (resource.relationships) {
-    for (const [relName, rel] of Object.entries(resource.relationships)) {
-      const relData = rel.data;
-      if (Array.isArray(relData)) {
-        out[relName] = relData
-          .map((ref) => {
-            const related = map[ref.type]?.[ref.id];
-            if (!related) return null;
-            return deep
-              ? hydrateOne(related, map, true, new Set(visited))
-              : { id: related.id, type: related.type, ...related.attributes };
-          })
-          .filter(Boolean);
-      } else if (relData) {
-        const related = map[relData.type]?.[relData.id];
-        out[relName] = related
-          ? (deep
-            ? hydrateOne(related, map, true, new Set(visited))
-            : { id: related.id, type: related.type, ...related.attributes })
-          : null;
-      } else {
-        out[relName] = null;
-      }
+  const resolve = (ref: { id: string; type: string }): unknown => {
+    const related = map[ref.type]?.[ref.id];
+    if (!related || nextPath.has(`${ref.type}:${ref.id}`)) return null;
+    return hydrateOne(related, map, descriptors, nextPath);
+  };
+
+  for (const [name, rel] of Object.entries(resource.relationships ?? {})) {
+    out[name] = Array.isArray(rel.data)
+      ? rel.data.map(resolve).filter((r) => r !== null)
+      : rel.data
+      ? resolve(rel.data)
+      : null;
+  }
+
+  const descriptor = descriptors[resource.type];
+  if (descriptor) {
+    for (const name of [...descriptor.attributes, ...descriptor.toOne]) {
+      out[name] ??= null;
+    }
+    for (const name of descriptor.toMany) {
+      out[name] ??= [];
     }
   }
   return out as T;
 }
 
 /**
- * Hydrates a JSON:API response, returning { data, meta, links }.
- * Preserves single vs array structure from input.
+ * Hydrates a JSON:API document into plain objects. Lists return
+ * `{ data, pagination }`; single resources return `{ data }`.
+ *
+ * Runtime validation is out of scope: the caller's `T` is trusted.
  */
-export function hydrateResponse<T = unknown>(
+export function hydrateResponse<T>(
   response: JsonApiSingleResponse,
-): HydratedSingleResult<T>;
-export function hydrateResponse<T = unknown>(
+  descriptors?: JsonApiResourceDescriptors,
+): HydratedSingle<T>;
+export function hydrateResponse<T>(
   response: JsonApiArrayResponse,
-): HydratedArrayResult<T>;
-export function hydrateResponse<T = unknown>(
-  response: JsonApiResponse | null | undefined,
-): HydratedSingleResult<T> | HydratedArrayResult<T> | null;
-export function hydrateResponse<T = unknown>(
-  response: JsonApiResponse | null | undefined,
-): HydratedSingleResult<T> | HydratedArrayResult<T> | null {
-  // Handle null/undefined input (e.g., from 204 No Content)
-  if (response === null || response === undefined) {
-    return null;
-  }
-
-  const { data, included, meta, links } = response;
-
-  // Preserve null for single resource responses (e.g., 204 No Content)
-  if (data === null) {
-    return { data: null, meta, links } as HydratedSingleResult<T>;
-  }
-
-  // Handle undefined/missing data as empty array
-  if (data === undefined) {
-    return { data: [] as T[], meta, links };
-  }
-
-  const map = buildResourceMap(included);
-
-  if (Array.isArray(data)) {
+  descriptors?: JsonApiResourceDescriptors,
+): HydratedList<T>;
+export function hydrateResponse<T>(
+  response: JsonApiSingleResponse | JsonApiArrayResponse,
+  descriptors: JsonApiResourceDescriptors = {},
+): HydratedSingle<T> | HydratedList<T> {
+  const map = buildIncludedMap(response.included);
+  if (Array.isArray(response.data)) {
     return {
-      data: data.map((res) => hydrateOne<T>(res, map, true, new Set())),
-      meta,
-      links,
+      data: response.data.map((res) =>
+        hydrateOne<T>(res, map, descriptors, new Set())
+      ),
+      pagination: response.meta?.pagination,
     };
   }
-
-  return {
-    data: hydrateOne<T>(data, map, true, new Set()),
-    meta,
-    links,
-  };
+  return { data: hydrateOne<T>(response.data, map, descriptors, new Set()) };
 }
diff --git a/clients/typescript/src/hydrate_test.ts b/clients/typescript/src/hydrate_test.ts
index 95597d4..2eb8d35 100644
--- a/clients/typescript/src/hydrate_test.ts
+++ b/clients/typescript/src/hydrate_test.ts
@@ -1,361 +1,153 @@
-// deno-lint-ignore-file no-explicit-any
 import { assertEquals } from '@std/assert';
 import { hydrateResponse } from './hydrate.ts';
 import type {
-  JsonApiArrayResponse,
-  JsonApiSingleResponse,
+  JsonApiResource,
+  JsonApiResourceDescriptor,
 } from './types/jsonapi.ts';
 
-Deno.test('hydrateResponse', async (t) => {
-  await t.step('hydrates array response with flattened attributes', () => {
-    const response: JsonApiArrayResponse = {
-      data: [
-        {
-          id: '1',
-          type: 'todos',
-          attributes: { title: 'Buy milk', completed: false },
-        },
-        {
-          id: '2',
-          type: 'todos',
-          attributes: { title: 'Walk dog', completed: true },
-        },
-      ],
-    };
+type User = { id: string; name: string; friend?: User | null };
+type Todo = {
+  id: string;
+  title: string;
+  owner?: User | null;
+  tags?: { id: string; label: string }[];
+};
 
-    const result = hydrateResponse(response);
+const alice: JsonApiResource = {
+  id: '10',
+  type: 'users',
+  attributes: { name: 'Alice' },
+};
 
-    assertEquals(result.data.length, 2);
-    assertEquals(result.data[0], {
-      id: '1',
-      type: 'todos',
-      title: 'Buy milk',
-      completed: false,
-    });
-    assertEquals(result.data[1], {
-      id: '2',
-      type: 'todos',
-      title: 'Walk dog',
-      completed: true,
+Deno.test('hydrateResponse', async (t) => {
+  await t.step('flattens attributes onto id, without type', () => {
+    const { data } = hydrateResponse<Todo>({
+      data: { id: '1', type: 'todos', attributes: { title: 'Buy milk' } },
     });
+    assertEquals(data, { id: '1', title: 'Buy milk' });
   });
 
-  await t.step('hydrates single resource response', () => {
-    const response: JsonApiSingleResponse = {
-      data: {
-        id: '1',
-        type: 'todos',
-        attributes: { title: 'Buy milk', completed: false },
-      },
+  await t.step('list returns data and pagination', () => {
+    const pagination = {
+      totalResources: 1,
+      totalPages: 1,
+      currentPage: 1,
+      pageSize: 10,
     };
-
-    const result = hydrateResponse(response);
-
-    assertEquals(result.data, {
-      id: '1',
-      type: 'todos',
-      title: 'Buy milk',
-      completed: false,
+    const result = hydrateResponse<Todo>({
+      data: [{ id: '1', type: 'todos', attributes: { title: 'Buy milk' } }],
+      meta: { pagination },
+      links: { self: '/todos' },
+    });
+    assertEquals(result, {
+      data: [{ id: '1', title: 'Buy milk' }],
+      pagination,
     });
   });
 
-  await t.step('resolves to-one relationship from included', () => {
-    const response: JsonApiSingleResponse = {
+  await t.step('resolves to-one and to-many from included', () => {
+    const { data } = hydrateResponse<Todo>({
       data: {
         id: '1',
         type: 'todos',
         attributes: { title: 'Buy milk' },
         relationships: {
           owner: { data: { id: '10', type: 'users' } },
+          tags: {
+            data: [{ id: '20', type: 'tags' }, { id: '21', type: 'tags' }],
+          },
         },
       },
       included: [
-        {
-          id: '10',
-          type: 'users',
-          attributes: { name: 'Alice', email: 'alice@example.com' },
-        },
+        alice,
+        { id: '20', type: 'tags', attributes: { label: 'urgent' } },
+        { id: '21', type: 'tags', attributes: { label: 'shopping' } },
       ],
-    };
-
-    const result = hydrateResponse(response);
-
-    assertEquals(result.data, {
-      id: '1',
-      type: 'todos',
-      title: 'Buy milk',
-      owner: {
-        id: '10',
-        type: 'users',
-        name: 'Alice',
-        email: 'alice@example.com',
-      },
     });
+    assertEquals(data.owner, { id: '10', name: 'Alice' });
+    assertEquals(data.tags, [
+      { id: '20', label: 'urgent' },
+      { id: '21', label: 'shopping' },
+    ]);
   });
 
-  await t.step('resolves to-many relationship from included', () => {
-    const response: JsonApiSingleResponse = {
+  await t.step('linked but not included: to-one null, to-many dropped', () => {
+    const { data } = hydrateResponse<Todo>({
       data: {
         id: '1',
         type: 'todos',
         attributes: { title: 'Buy milk' },
         relationships: {
+          owner: { data: { id: '99', type: 'users' } },
           tags: {
-            data: [
-              { id: '20', type: 'tags' },
-              { id: '21', type: 'tags' },
-            ],
+            data: [{ id: '20', type: 'tags' }, { id: '99', type: 'tags' }],
           },
         },
       },
-      included: [
-        { id: '20', type: 'tags', attributes: { label: 'urgent' } },
-        { id: '21', type: 'tags', attributes: { label: 'shopping' } },
-      ],
-    };
-
-    const result = hydrateResponse(response);
-
-    assertEquals(result.data, {
-      id: '1',
-      type: 'todos',
-      title: 'Buy milk',
-      tags: [
-        { id: '20', type: 'tags', label: 'urgent' },
-        { id: '21', type: 'tags', label: 'shopping' },
-      ],
+      included: [{ id: '20', type: 'tags', attributes: { label: 'urgent' } }],
     });
+    assertEquals(data.owner, null);
+    assertEquals(data.tags, [{ id: '20', label: 'urgent' }]);
   });
 
-  await t.step('handles circular references without infinite loop', () => {
-    const response: JsonApiSingleResponse = {
+  await t.step('empty to-one relationship is null', () => {
+    const { data } = hydrateResponse<Todo>({
       data: {
         id: '1',
-        type: 'users',
-        attributes: { name: 'Alice' },
-        relationships: {
-          friend: { data: { id: '2', type: 'users' } },
-        },
+        type: 'todos',
+        attributes: { title: 'Buy milk' },
+        relationships: { owner: { data: null } },
       },
-      included: [
-        {
-          id: '2',
-          type: 'users',
-          attributes: { name: 'Bob' },
-          relationships: {
-            friend: { data: { id: '1', type: 'users' } },
-          },
-        },
-        {
-          id: '1',
-          type: 'users',
-          attributes: { name: 'Alice' },
-          relationships: {
-            friend: { data: { id: '2', type: 'users' } },
-          },
-        },
-      ],
-    };
-
-    const result = hydrateResponse(response);
-
-    // Alice -> Bob resolves, Bob -> Alice hits circular guard
-    const data = result.data as any;
-    assertEquals(data.id, '1');
-    assertEquals(data.name, 'Alice');
-    assertEquals(data.friend.id, '2');
-    assertEquals(data.friend.name, 'Bob');
-    assertEquals(data.friend.friend, {
-      id: '1',
-      type: 'users',
-      circular: true,
     });
+    assertEquals(data.owner, null);
   });
 
-  await t.step('returns null for null input', () => {
-    const result = hydrateResponse(null);
-    assertEquals(result, null);
-  });
-
-  await t.step('returns null for undefined input', () => {
-    const result = hydrateResponse(undefined);
-    assertEquals(result, null);
-  });
-
-  await t.step('preserves null data in single resource response', () => {
-    const response = { data: null } as any;
-    const result = hydrateResponse(response);
-
-    assertEquals(result.data, null);
-  });
-
-  await t.step(
-    'resolves missing to-one relationship to null',
-    () => {
-      const response: JsonApiSingleResponse = {
-        data: {
-          id: '1',
-          type: 'todos',
-          attributes: { title: 'Buy milk' },
-          relationships: {
-            owner: { data: { id: '99', type: 'users' } },
-          },
-        },
-        included: [],
-      };
-
-      const result = hydrateResponse(response);
-
-      assertEquals((result.data as any).owner, null);
-    },
-  );
-
-  await t.step(
-    'filters out missing to-many relationship entries',
-    () => {
-      const response: JsonApiSingleResponse = {
-        data: {
-          id: '1',
-          type: 'todos',
-          attributes: { title: 'Buy milk' },
-          relationships: {
-            tags: {
-              data: [
-                { id: '20', type: 'tags' },
-                { id: '99', type: 'tags' },
-              ],
-            },
-          },
-        },
-        included: [
-          { id: '20', type: 'tags', attributes: { label: 'urgent' } },
-        ],
-      };
-
-      const result = hydrateResponse(response);
-
-      assertEquals((result.data as any).tags.length, 1);
-      assertEquals((result.data as any).tags[0].label, 'urgent');
-    },
-  );
-
-  await t.step('resolves deep nested relationships', () => {
-    const response: JsonApiSingleResponse = {
-      data: {
-        id: '1',
-        type: 'todos',
-        attributes: { title: 'Buy milk' },
-        relationships: {
-          owner: { data: { id: '10', type: 'users' } },
-        },
-      },
-      included: [
-        {
-          id: '10',
-          type: 'users',
-          attributes: { name: 'Alice' },
-          relationships: {
-            department: { data: { id: '100', type: 'departments' } },
-          },
-        },
-        {
-          id: '100',
-          type: 'departments',
-          attributes: { name: 'Engineering' },
-        },
-      ],
+  await t.step('descriptor fills what the wire omits', () => {
+    type Article = {
+      id: string;
+      title: string;
+      body: string | null;
+      author: User | null;
+      comments: { id: string }[];
     };
-
-    const result = hydrateResponse(response);
-
-    assertEquals((result.data as any).owner.name, 'Alice');
-    assertEquals((result.data as any).owner.department, {
-      id: '100',
-      type: 'departments',
-      name: 'Engineering',
+    const descriptors = {
+      articles: {
+        type: 'articles',
+        attributes: ['title', 'body'],
+        toOne: ['author'],
+        toMany: ['comments'],
+      } satisfies JsonApiResourceDescriptor<Article>,
+    };
+    const { data } = hydrateResponse<Article>(
+      // body is null-stripped, author and comments are not included
+      { data: { id: '1', type: 'articles', attributes: { title: 'A' } } },
+      descriptors,
+    );
+    assertEquals(data, {
+      id: '1',
+      title: 'A',
+      body: null,
+      author: null,
+      comments: [],
     });
   });
 
-  await t.step('handles empty included array', () => {
-    const response: JsonApiSingleResponse = {
+  await t.step('resolves nested includes, cycles stop at null', () => {
+    const { data } = hydrateResponse<User>({
       data: {
         id: '1',
-        type: 'todos',
-        attributes: { title: 'Buy milk' },
-        relationships: {
-          owner: { data: { id: '10', type: 'users' } },
-        },
+        type: 'users',
+        attributes: { name: 'Zed' },
+        relationships: { friend: { data: { id: '10', type: 'users' } } },
       },
-      included: [],
-    };
-
-    const result = hydrateResponse(response);
-
-    assertEquals((result.data as any).owner, null);
-  });
-
-  await t.step('propagates meta and links', () => {
-    const response: JsonApiArrayResponse = {
-      data: [
+      included: [
         {
-          id: '1',
-          type: 'todos',
-          attributes: { title: 'Buy milk' },
+          ...alice,
+          relationships: { friend: { data: { id: '1', type: 'users' } } },
         },
       ],
-      meta: {
-        pagination: {
-          totalResources: 100,
-          totalPages: 10,
-          currentPage: 1,
-          pageSize: 10,
-        },
-      },
-      links: {
-        self: '/api/todos?page[number]=1',
-        next: '/api/todos?page[number]=2',
-        last: '/api/todos?page[number]=10',
-      },
-    };
-
-    const result = hydrateResponse(response);
-
-    assertEquals(result.meta, {
-      pagination: {
-        totalResources: 100,
-        totalPages: 10,
-        currentPage: 1,
-        pageSize: 10,
-      },
-    });
-    assertEquals(result.links, {
-      self: '/api/todos?page[number]=1',
-      next: '/api/todos?page[number]=2',
-      last: '/api/todos?page[number]=10',
     });
-  });
-
-  await t.step('handles undefined data as empty array', () => {
-    const response = {} as any;
-    const result = hydrateResponse(response);
-
-    assertEquals(result.data, []);
-  });
-
-  await t.step('resolves null to-one relationship data', () => {
-    const response: JsonApiSingleResponse = {
-      data: {
-        id: '1',
-        type: 'todos',
-        attributes: { title: 'Buy milk' },
-        relationships: {
-          owner: { data: null },
-        },
-      },
-    };
-
-    const result = hydrateResponse(response);
-
-    assertEquals((result.data as any).owner, null);
+    assertEquals(data.friend?.name, 'Alice');
+    assertEquals(data.friend?.friend, null);
   });
 });
diff --git a/clients/typescript/src/index.ts b/clients/typescript/src/index.ts
index 430c0c2..fe544d4 100644
--- a/clients/typescript/src/index.ts
+++ b/clients/typescript/src/index.ts
@@ -1,3 +1,43 @@
+/**
+ * TypeScript tools for JSON:API responses from
+ * [JsonApiToolkit](https://github.com/intility/json-api-toolkit) backends.
+ *
+ * The library has four parts:
+ *
+ * - **Client**: `createJsonApiClient` builds a fetch-based client. Its
+ *   `resource<T>(path)` handles cover query building, hydration, and error
+ *   handling for reads and writes in one call path.
+ * - **Hydration**: `hydrateResponse` resolves relationships from the
+ *   `included` array and returns plain objects as `{ data, meta, links }`.
+ *   Used internally by the client; exported for interop.
+ * - **Query builder**: `JsonApiQueryBuilder` builds type-safe JSON:API
+ *   query strings with filters, sorts, includes, sparse fieldsets, and
+ *   pagination.
+ * - **Error types**: JSON:API error types, the `isJsonApiErrorResponse`
+ *   type guard, and `JsonApiRequestError` (thrown by the client on
+ *   non-2xx responses), matching the C# toolkit's error model.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createJsonApiClient } from '@intility/json-api-client';
+ *
+ * const client = createJsonApiClient({ baseUrl: '/api', fetch });
+ * const books = client.resource<Book>('books');
+ *
+ * const { data, pagination } = await books.list((q) =>
+ *   q.filter('author.name', 'John').include('author').page(1, 25));
+ *
+ * const book = await books.get(id, (q) => q.include('author'));
+ * const created = await books.post({ title: '...' });
+ * await books.patch(created.id, { title: 'renamed' });
+ * await books.delete(created.id);
+ * ```
+ *
+ * @module
+ */
+
+export * from './client.ts';
 export * from './hydrate.ts';
 export * from './errors.ts';
 export * from './types/jsonapi.ts';
diff --git a/clients/typescript/src/query-builder/FilterGroupBuilder.ts b/clients/typescript/src/query-builder/FilterGroupBuilder.ts
index 8c4386a..ac06714 100644
--- a/clients/typescript/src/query-builder/FilterGroupBuilder.ts
+++ b/clients/typescript/src/query-builder/FilterGroupBuilder.ts
@@ -1,68 +1,29 @@
-// deno-lint-ignore-file no-explicit-any
 import type { AttributeKeys, FilterOp } from '../types/query-builder.ts';
-import type { FilterGroup } from '../types/filters.ts';
+import type { SimpleFilter } from '../types/filters.ts';
 
 /**
- * Builder for logical filter groups (or, and, not).
- * Alows for chaining and nesting of filter groups.
+ * Builder for the flat filter list inside an `or()`/`not()` group.
+ * No nesting: the backend only parses one flat level of a logical group.
  */
 export class FilterGroupBuilder<T> {
-  private groups: FilterGroup<T>[] = [];
+  private filters: SimpleFilter<T>[] = [];
 
   /**
    * Add a simple filter to this group.
    */
-  filter<K extends AttributeKeys<T>>(field: K, op: FilterOp, value: any) {
-    this.groups.push({
-      type: 'simple',
-      filter: { field, op, value },
-    });
+  filter<K extends AttributeKeys<T>>(
+    field: K,
+    op: FilterOp,
+    value: unknown,
+  ): this {
+    this.filters.push({ field, op, value });
     return this;
   }
 
   /**
-   * Add an "or" logical group to this group.
+   * Returns the built flat filter list.
    */
-  or(cb: (b: FilterGroupBuilder<T>) => void) {
-    const builder = new FilterGroupBuilder<T>();
-    cb(builder);
-    this.groups.push({
-      type: 'or',
-      filters: builder.groups,
-    });
-    return this;
-  }
-
-  /**
-   * Add an "and" logical group to this group.
-   */
-  and(cb: (b: FilterGroupBuilder<T>) => void) {
-    const builder = new FilterGroupBuilder<T>();
-    cb(builder);
-    this.groups.push({
-      type: 'and',
-      filters: builder.groups,
-    });
-    return this;
-  }
-
-  /**
-   * Add a "not" logical group to this group.
-   */
-  not(cb: (b: FilterGroupBuilder<T>) => void) {
-    const builder = new FilterGroupBuilder<T>();
-    cb(builder);
-    this.groups.push({
-      type: 'not',
-      filters: builder.groups,
-    });
-    return this;
-  }
-
-  /**
-   * Returns the built filter group array.
-   */
-  build(): FilterGroup<T>[] {
-    return this.groups;
+  build(): SimpleFilter<T>[] {
+    return this.filters;
   }
 }
diff --git a/clients/typescript/src/query-builder/FilterGroupBuilder_test.ts b/clients/typescript/src/query-builder/FilterGroupBuilder_test.ts
index df13560..b23d862 100644
--- a/clients/typescript/src/query-builder/FilterGroupBuilder_test.ts
+++ b/clients/typescript/src/query-builder/FilterGroupBuilder_test.ts
@@ -15,7 +15,7 @@ Deno.test('FilterGroupBuilder', async (t) => {
     builder.filter('title', 'eq', 'hello');
 
     assertEquals(builder.build(), [
-      { type: 'simple', filter: { field: 'title', op: 'eq', value: 'hello' } },
+      { field: 'title', op: 'eq', value: 'hello' },
     ]);
   });
 
@@ -26,83 +26,8 @@ Deno.test('FilterGroupBuilder', async (t) => {
 
     const result = builder.build();
     assertEquals(result.length, 2);
-    assertEquals(result[0], {
-      type: 'simple',
-      filter: { field: 'title', op: 'eq', value: 'hello' },
-    });
-    assertEquals(result[1], {
-      type: 'simple',
-      filter: { field: 'completed', op: 'eq', value: true },
-    });
-  });
-
-  await t.step('nested or group', () => {
-    const builder = new FilterGroupBuilder<Todo>();
-    builder.or((b) => {
-      b.filter('title', 'eq', 'A');
-      b.filter('title', 'eq', 'B');
-    });
-
-    assertEquals(builder.build(), [
-      {
-        type: 'or',
-        filters: [
-          {
-            type: 'simple',
-            filter: { field: 'title', op: 'eq', value: 'A' },
-          },
-          {
-            type: 'simple',
-            filter: { field: 'title', op: 'eq', value: 'B' },
-          },
-        ],
-      },
-    ]);
-  });
-
-  await t.step('nested and group', () => {
-    const builder = new FilterGroupBuilder<Todo>();
-    builder.and((b) => {
-      b.filter('completed', 'eq', true);
-      b.filter('dueDate', 'gt', '2025-01-01');
-    });
-
-    const result = builder.build();
-    assertEquals(result.length, 1);
-    assertEquals(result[0].type, 'and');
-  });
-
-  await t.step('nested not group', () => {
-    const builder = new FilterGroupBuilder<Todo>();
-    builder.not((b) => {
-      b.filter('completed', 'eq', true);
-    });
-
-    const result = builder.build();
-    assertEquals(result.length, 1);
-    assertEquals(result[0].type, 'not');
-  });
-
-  await t.step('deeply nested groups', () => {
-    const builder = new FilterGroupBuilder<Todo>();
-    builder.or((b) => {
-      b.filter('title', 'eq', 'A');
-      b.and((inner) => {
-        inner.filter('completed', 'eq', true);
-        inner.filter('dueDate', 'lt', '2025-12-31');
-      });
-    });
-
-    const result = builder.build();
-    assertEquals(result.length, 1);
-    assertEquals(result[0].type, 'or');
-
-    // Verify the inner structure
-    if (result[0].type !== 'simple') {
-      assertEquals(result[0].filters.length, 2);
-      assertEquals(result[0].filters[0].type, 'simple');
-      assertEquals(result[0].filters[1].type, 'and');
-    }
+    assertEquals(result[0], { field: 'title', op: 'eq', value: 'hello' });
+    assertEquals(result[1], { field: 'completed', op: 'eq', value: true });
   });
 
   await t.step('empty builder returns empty array', () => {
diff --git a/clients/typescript/src/query-builder/FilterGroupBuilder_types_test.ts b/clients/typescript/src/query-builder/FilterGroupBuilder_types_test.ts
new file mode 100644
index 0000000..a3e2866
--- /dev/null
+++ b/clients/typescript/src/query-builder/FilterGroupBuilder_types_test.ts
@@ -0,0 +1,56 @@
+/**
+ * Type-level probes: nesting a logical group, or using `.and()`, must be a
+ * compile error. The backend only parses one flat level (see DESIGN.md),
+ * so the builder must not be able to express what it cannot carry.
+ *
+ * Wrapped in an uncalled function: `deno check` still type-checks the body,
+ * but nothing here runs, so the `@ts-expect-error` calls never throw.
+ */
+import { FilterGroupBuilder } from './FilterGroupBuilder.ts';
+import { JsonApiQueryBuilder } from './JsonApiQueryBuilder.ts';
+
+interface User {
+  id: string;
+  type: string;
+  name: string;
+}
+
+interface Todo {
+  id: string;
+  type: string;
+  title: string;
+  completed: boolean;
+  owner: User | null;
+}
+
+function _typeOnlyProbes() {
+  new JsonApiQueryBuilder<Todo>().or((b) => {
+    b.filter('title', 'eq', 'A');
+    // @ts-expect-error groups only take flat filters, no nested or/and/not
+    b.or((inner) => inner.filter('completed', 'eq', true));
+  });
+
+  const builder = new FilterGroupBuilder<Todo>();
+  // @ts-expect-error "and" is removed everywhere: top-level filters are already AND'd
+  builder.and((b) => b.filter('completed', 'eq', true));
+
+  const outer = new JsonApiQueryBuilder<Todo>();
+  // @ts-expect-error "and" is removed everywhere: top-level filters are already AND'd
+  outer.and((b) => b.filter('completed', 'eq', true));
+
+  const nullCheck = new JsonApiQueryBuilder<Todo>();
+  // @ts-expect-error isnull/isnotnull are not valid ops for the 3-arg form; use filterNull()/filterNotNull()
+  nullCheck.filter('completed', 'isnull', true);
+
+  const included = new JsonApiQueryBuilder<Todo>();
+  // @ts-expect-error "title" is not an attribute of the "owner" relationship's type
+  included.filterIncluded('owner', 'title', 'eq', 'x');
+
+  const sorter = new JsonApiQueryBuilder<Todo>();
+  // @ts-expect-error sort() is direct attributes only; the backend silently ignores a dot-path sort field
+  sorter.sort('owner.name');
+}
+
+Deno.test('type probes compile', () => {
+  void _typeOnlyProbes;
+});
diff --git a/clients/typescript/src/query-builder/JsonApiQueryBuilder.ts b/clients/typescript/src/query-builder/JsonApiQueryBuilder.ts
index 5770f49..e0b167a 100644
--- a/clients/typescript/src/query-builder/JsonApiQueryBuilder.ts
+++ b/clients/typescript/src/query-builder/JsonApiQueryBuilder.ts
@@ -1,35 +1,60 @@
-// deno-lint-ignore-file no-explicit-any
 import type {
   AttributeKeys,
   DirectAttributeKeys,
   FilterOp,
   Include,
+  IncludedAttributeKeys,
+  RelationshipKeys,
   Sort,
 } from '../types/query-builder.ts';
 import { FilterGroupBuilder } from './FilterGroupBuilder.ts';
 import type { FilterGroup } from '../types/filters.ts';
+import type {
+  JsonApiResourceDescriptor,
+  JsonApiResourceDescriptorBase,
+} from '../types/jsonapi.ts';
+
+/**
+ * Serializes a filter value to its wire string. `Date` becomes ISO 8601
+ * (not `String(date)`'s locale format, which the backend can't parse).
+ * Arrays (for `in`/`nin`) join with commas; there is no escaping for a
+ * comma inside an array element's own value.
+ */
+function serializeValue(value: unknown): string {
+  if (Array.isArray(value)) {
+    return value.map(serializeValue).join(',');
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return String(value);
+}
+
+/**
+ * Serializes one attribute filter into a `filter[...]` query parameter.
+ */
+function serializeSimpleFilter(
+  filter: { field: unknown; op: string; value: unknown },
+  prefix: string[],
+): [string, string] {
+  const { field, op, value } = filter;
+  const key = op === 'eq'
+    ? [...prefix, String(field)]
+    : [...prefix, String(field), op];
+  return [`filter${key.map((k) => `[${k}]`).join('')}`, serializeValue(value)];
+}
 
 /**
- * Recursively serializes a filter group into JSON:API query parameter key-value pairs.
+ * Serializes a filter group (a simple filter, or a flat or/not group) into
+ * JSON:API query parameter key-value pairs.
  */
-function serializeFilterGroup<T>(
-  group: FilterGroup<T>,
-  prefix: string[] = [],
-): [string, string][] {
+function serializeFilterGroup<T>(group: FilterGroup<T>): [string, string][] {
   if (group.type === 'simple') {
-    const { field, op, value } = group.filter;
-    const key = op === 'eq'
-      ? [...prefix, String(field)]
-      : [...prefix, String(field), op];
-    let val = value;
-    if (Array.isArray(value)) val = value.join(',');
-    return [[`filter${key.map((k) => `[${k}]`).join('')}`, String(val)]];
-  } else {
-    // Logical group (or, and, not)
-    return group.filters.flatMap((f, i) =>
-      serializeFilterGroup(f, [...prefix, group.type, String(i)])
-    );
+    return [serializeSimpleFilter(group.filter, [])];
   }
+  return group.filters.map((f, i) =>
+    serializeSimpleFilter(f, [group.type, String(i)])
+  );
 }
 
 /**
@@ -38,6 +63,12 @@ function serializeFilterGroup<T>(
  */
 export class JsonApiQueryBuilder<T> {
   private filterGroups: FilterGroup<T>[] = [];
+  private includeFilters: {
+    relationship: string;
+    field: string;
+    op: FilterOp;
+    value: unknown;
+  }[] = [];
   private sorts: Sort<T> = [];
   private includes: Include<T> = [];
   private pagination: { number?: number; size?: number } = {};
@@ -47,21 +78,30 @@ export class JsonApiQueryBuilder<T> {
    * Add a simple filter.
    * @param field - The attribute to filter on
    * @param value - The value to filter by (uses "eq" operator)
+   *
+   * Note: TypeScript cannot reject the literal strings "isnull"/"isnotnull"
+   * here without also rejecting every other free-form string value, so this
+   * still compiles but produces meaningless wire output. Use `filterNull()`/
+   * `filterNotNull()` for null checks.
    */
-  filter<K extends AttributeKeys<T>>(field: K, value: any): this;
+  filter<K extends AttributeKeys<T>>(field: K, value: unknown): this;
   /**
    * Add a simple filter with explicit operator.
    * @param field - The attribute to filter on
    * @param op - The filter operator
    * @param value - The value to filter by
    */
-  filter<K extends AttributeKeys<T>>(field: K, op: FilterOp, value: any): this;
   filter<K extends AttributeKeys<T>>(
     field: K,
-    opOrValue: FilterOp | any,
-    value?: any,
-  ) {
-    const op: FilterOp = value === undefined ? 'eq' : opOrValue;
+    op: FilterOp,
+    value: unknown,
+  ): this;
+  filter<K extends AttributeKeys<T>>(
+    field: K,
+    opOrValue: unknown,
+    value?: unknown,
+  ): this {
+    const op = value === undefined ? 'eq' : (opOrValue as FilterOp);
     const val = value === undefined ? opOrValue : value;
     this.filterGroups.push({
       type: 'simple',
@@ -71,26 +111,61 @@ export class JsonApiQueryBuilder<T> {
   }
 
   /**
-   * Add an "or" logical filter group.
+   * Filter where the attribute is null: `filter[field][isnull]`.
+   * The wire ignores the filter value for this operator; only its
+   * presence matters.
    */
-  or(cb: (b: FilterGroupBuilder<T>) => void) {
-    const builder = new FilterGroupBuilder<T>();
-    cb(builder);
+  filterNull<K extends AttributeKeys<T>>(field: K): this {
     this.filterGroups.push({
-      type: 'or',
-      filters: builder.build(),
+      type: 'simple',
+      filter: { field, op: 'isnull', value: true },
     });
     return this;
   }
 
   /**
-   * Add an "and" logical filter group.
+   * Filter where the attribute is not null: `filter[field][isnotnull]`.
+   * The wire ignores the filter value for this operator; only its
+   * presence matters.
    */
-  and(cb: (b: FilterGroupBuilder<T>) => void) {
+  filterNotNull<K extends AttributeKeys<T>>(field: K): this {
+    this.filterGroups.push({
+      type: 'simple',
+      filter: { field, op: 'isnotnull', value: true },
+    });
+    return this;
+  }
+
+  /**
+   * Filter an included relationship, trimming what comes back in `included`:
+   * `filter[relationship][field][op]=value`. Distinct from dot-path
+   * filtering (`.filter("owner.name", ...)`), which filters the primary
+   * resource by a related field instead. Requires the relationship to also
+   * be passed to `.include()`, or the backend drops the filter.
+   */
+  filterIncluded<R extends RelationshipKeys<T>>(
+    relationship: R,
+    field: IncludedAttributeKeys<T, R>,
+    op: FilterOp,
+    value: unknown,
+  ): this {
+    this.includeFilters.push({
+      relationship: String(relationship),
+      field: String(field),
+      op,
+      value,
+    });
+    return this;
+  }
+
+  /**
+   * Add an "or" logical filter group.
+   */
+  or(cb: (b: FilterGroupBuilder<T>) => void): this {
     const builder = new FilterGroupBuilder<T>();
     cb(builder);
     this.filterGroups.push({
-      type: 'and',
+      type: 'or',
       filters: builder.build(),
     });
     return this;
@@ -99,7 +174,7 @@ export class JsonApiQueryBuilder<T> {
   /**
    * Add a "not" logical filter group.
    */
-  not(cb: (b: FilterGroupBuilder<T>) => void) {
+  not(cb: (b: FilterGroupBuilder<T>) => void): this {
     const builder = new FilterGroupBuilder<T>();
     cb(builder);
     this.filterGroups.push({
@@ -110,40 +185,50 @@ export class JsonApiQueryBuilder<T> {
   }
 
   /**
-   * Set sort fields (comma-separated, supports -field for descending).
+   * Add sort fields (supports -field for descending). Repeat calls append,
+   * same as `filter()`, instead of replacing the previous fields.
    */
-  sort(...fields: Sort<T>) {
-    this.sorts = fields;
+  sort(...fields: Sort<T>): this {
+    this.sorts.push(...fields);
     return this;
   }
 
   /**
-   * Set included relationships (comma-separated, supports dot notation).
+   * Add included relationships (supports dot notation). Repeat calls
+   * append, same as `filter()`, instead of replacing the previous fields.
    */
-  include(...fields: Include<T>) {
-    this.includes = fields;
+  include(...fields: Include<T>): this {
+    this.includes.push(...fields);
     return this;
   }
 
   /**
-   * Set sparse fieldsets for a resource type.
-   * Produces `fields[type]=field1,field2` in the query string.
-   * Pass a type parameter for type-safe field suggestions.
-   * @param type - The JSON:API resource type name
-   * @param fields - The attribute names to include
+   * Set a sparse fieldset for a resource: `fields[type]=field1,field2`.
+   * Pass a generated descriptor for the wire type and typed field names.
    */
-  fields<R = unknown>(
-    type: string,
-    fields: (unknown extends R ? string : DirectAttributeKeys<R>)[],
-  ) {
-    this.fieldsets.set(type, fields as string[]);
+  fields<R>(
+    descriptor: JsonApiResourceDescriptor<R>,
+    fields: DirectAttributeKeys<R>[],
+  ): this;
+  /** Sparse fieldset by wire type name, untyped field names. */
+  fields(type: string, fields: string[]): this;
+  /** Sparse fieldset by wire type name, field names typed against `R`. */
+  fields<R>(type: string, fields: DirectAttributeKeys<R>[]): this;
+  fields(
+    source: string | JsonApiResourceDescriptorBase,
+    fields: string[],
+  ): this {
+    this.fieldsets.set(
+      typeof source === 'string' ? source : source.type,
+      fields,
+    );
     return this;
   }
 
   /**
    * Set pagination (page number and size).
    */
-  page(number: number, size: number) {
+  page(number: number, size: number): this {
     this.pagination = { number, size };
     return this;
   }
@@ -161,6 +246,16 @@ export class JsonApiQueryBuilder<T> {
       }
     }
 
+    // Included-relationship filters: filter[relationship][field][op]=value.
+    // Unlike a plain filter, the op segment is never omitted for "eq": the
+    // backend's bracket-filter parser always expects exactly 3 segments.
+    for (const { relationship, field, op, value } of this.includeFilters) {
+      params.append(
+        `filter[${relationship}][${field}][${op}]`,
+        serializeValue(value),
+      );
+    }
+
     // Sort
     if (this.sorts.length) {
       params.append('sort', this.sorts.join(','));
diff --git a/clients/typescript/src/query-builder/JsonApiQueryBuilder_test.ts b/clients/typescript/src/query-builder/JsonApiQueryBuilder_test.ts
index f4697b2..59edb7d 100644
--- a/clients/typescript/src/query-builder/JsonApiQueryBuilder_test.ts
+++ b/clients/typescript/src/query-builder/JsonApiQueryBuilder_test.ts
@@ -1,5 +1,6 @@
 import { assertEquals } from '@std/assert';
 import { JsonApiQueryBuilder } from './JsonApiQueryBuilder.ts';
+import type { JsonApiResourceDescriptor } from '../types/jsonapi.ts';
 
 interface User {
   id: string;
@@ -29,6 +30,14 @@ function parse(query: string): URLSearchParams {
   return new URLSearchParams(query);
 }
 
+/** Fixture as `dotnet jsonapi-typegen` would emit it next to `Todo`. */
+const TodoDescriptor: JsonApiResourceDescriptor<Todo> = {
+  type: 'todos',
+  attributes: ['title', 'completed', 'dueDate'],
+  toOne: ['owner'],
+  toMany: ['tags'],
+};
+
 Deno.test('JsonApiQueryBuilder', async (t) => {
   // --- Filters ---
 
@@ -67,6 +76,34 @@ Deno.test('JsonApiQueryBuilder', async (t) => {
     assertEquals(parse(qs).get('filter[title][in]'), 'a,b,c');
   });
 
+  await t.step('Date value serializes to ISO 8601, not a locale string', () => {
+    const qs = new JsonApiQueryBuilder<Todo>()
+      .filter('dueDate', 'gt', new Date('2025-01-20T00:00:00.000Z'))
+      .build();
+
+    assertEquals(
+      parse(qs).get('filter[dueDate][gt]'),
+      '2025-01-20T00:00:00.000Z',
+    );
+  });
+
+  await t.step(
+    'array of Date values in an "in" filter also serializes to ISO',
+    () => {
+      const qs = new JsonApiQueryBuilder<Todo>()
+        .filter('dueDate', 'in', [
+          new Date('2025-01-01T00:00:00.000Z'),
+          new Date('2025-02-01T00:00:00.000Z'),
+        ])
+        .build();
+
+      assertEquals(
+        parse(qs).get('filter[dueDate][in]'),
+        '2025-01-01T00:00:00.000Z,2025-02-01T00:00:00.000Z',
+      );
+    },
+  );
+
   await t.step('nested attribute filter (dot notation)', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
       .filter('owner.name', 'Alice')
@@ -75,62 +112,75 @@ Deno.test('JsonApiQueryBuilder', async (t) => {
     assertEquals(parse(qs).get('filter[owner.name]'), 'Alice');
   });
 
-  // --- Logical groups ---
-
-  await t.step('or() group', () => {
+  await t.step('deep dot-path filter (escape hatch, 2+ levels)', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
-      .or((b) => {
-        b.filter('title', 'eq', 'A');
-        b.filter('title', 'eq', 'B');
-      })
+      .filter('owner.company.name', 'eq', 'Acme')
       .build();
 
-    const params = parse(qs);
-    assertEquals(params.get('filter[or][0][title]'), 'A');
-    assertEquals(params.get('filter[or][1][title]'), 'B');
+    assertEquals(parse(qs).get('filter[owner.company.name]'), 'Acme');
   });
 
-  await t.step('and() group', () => {
+  await t.step('filterNull() emits filter[field][isnull]', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
-      .and((b) => {
-        b.filter('completed', 'eq', 'true');
-        b.filter('title', 'like', '%urgent%');
-      })
+      .filterNull('dueDate')
       .build();
 
-    const params = parse(qs);
-    assertEquals(params.get('filter[and][0][completed]'), 'true');
-    assertEquals(params.get('filter[and][1][title][like]'), '%urgent%');
+    assertEquals(parse(qs).get('filter[dueDate][isnull]'), 'true');
   });
 
-  await t.step('not() group', () => {
+  await t.step('filterNotNull() emits filter[field][isnotnull]', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
-      .not((b) => {
-        b.filter('completed', 'eq', 'true');
-      })
+      .filterNotNull('dueDate')
       .build();
 
-    assertEquals(parse(qs).get('filter[not][0][completed]'), 'true');
+    assertEquals(parse(qs).get('filter[dueDate][isnotnull]'), 'true');
   });
 
-  await t.step('nested logical groups', () => {
+  await t.step(
+    'filterIncluded() on a to-one relationship emits filter[rel][field][op]',
+    () => {
+      const qs = new JsonApiQueryBuilder<Todo>()
+        .filterIncluded('owner', 'name', 'like', 'Ali')
+        .build();
+
+      assertEquals(parse(qs).get('filter[owner][name][like]'), 'Ali');
+    },
+  );
+
+  await t.step(
+    'filterIncluded() on a to-many relationship emits filter[rel][field][op]',
+    () => {
+      const qs = new JsonApiQueryBuilder<Todo>()
+        .filterIncluded('tags', 'label', 'eq', 'urgent')
+        .build();
+
+      assertEquals(parse(qs).get('filter[tags][label][eq]'), 'urgent');
+    },
+  );
+
+  // --- Logical groups ---
+
+  await t.step('or() group', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
       .or((b) => {
         b.filter('title', 'eq', 'A');
-        b.and((inner) => {
-          inner.filter('completed', 'eq', 'true');
-          inner.filter('dueDate', 'gt', '2025-01-01');
-        });
+        b.filter('title', 'eq', 'B');
       })
       .build();
 
     const params = parse(qs);
     assertEquals(params.get('filter[or][0][title]'), 'A');
-    assertEquals(params.get('filter[or][1][and][0][completed]'), 'true');
-    assertEquals(
-      params.get('filter[or][1][and][1][dueDate][gt]'),
-      '2025-01-01',
-    );
+    assertEquals(params.get('filter[or][1][title]'), 'B');
+  });
+
+  await t.step('not() group', () => {
+    const qs = new JsonApiQueryBuilder<Todo>()
+      .not((b) => {
+        b.filter('completed', 'eq', 'true');
+      })
+      .build();
+
+    assertEquals(parse(qs).get('filter[not][0][completed]'), 'true');
   });
 
   // --- Sorting ---
@@ -159,6 +209,15 @@ Deno.test('JsonApiQueryBuilder', async (t) => {
     assertEquals(parse(qs).get('sort'), 'title,-dueDate');
   });
 
+  await t.step('repeat sort() calls append, same as filter()', () => {
+    const qs = new JsonApiQueryBuilder<Todo>()
+      .sort('title')
+      .sort('-dueDate')
+      .build();
+
+    assertEquals(parse(qs).get('sort'), 'title,-dueDate');
+  });
+
   // --- Includes ---
 
   await t.step('include relationships', () => {
@@ -169,6 +228,15 @@ Deno.test('JsonApiQueryBuilder', async (t) => {
     assertEquals(parse(qs).get('include'), 'owner,tags');
   });
 
+  await t.step('repeat include() calls append, same as filter()', () => {
+    const qs = new JsonApiQueryBuilder<Todo>()
+      .include('owner')
+      .include('tags')
+      .build();
+
+    assertEquals(parse(qs).get('include'), 'owner,tags');
+  });
+
   await t.step('include with dot notation', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
       .include('owner.department')
@@ -187,6 +255,14 @@ Deno.test('JsonApiQueryBuilder', async (t) => {
     assertEquals(parse(qs).get('fields[todos]'), 'title,completed');
   });
 
+  await t.step('fields from a generated resource descriptor', () => {
+    const qs = new JsonApiQueryBuilder<Todo>()
+      .fields(TodoDescriptor, ['title', 'completed'])
+      .build();
+
+    assertEquals(parse(qs).get('fields[todos]'), 'title,completed');
+  });
+
   await t.step('fields for multiple resource types', () => {
     const qs = new JsonApiQueryBuilder<Todo>()
       .fields('todos', ['title'])
diff --git a/clients/typescript/src/types/filters.ts b/clients/typescript/src/types/filters.ts
index b634727..bd7bd3c 100644
--- a/clients/typescript/src/types/filters.ts
+++ b/clients/typescript/src/types/filters.ts
@@ -1,23 +1,24 @@
-// deno-lint-ignore-file no-explicit-any
-import type { AttributeKeys, FilterOp } from './query-builder.ts';
+import type { AttributeKeys, WireFilterOp } from './query-builder.ts';
 
 /**
  * Represents a simple filter on a single attribute.
  */
 export type SimpleFilter<T> = {
   field: AttributeKeys<T>;
-  op: FilterOp;
-  value: any;
+  op: WireFilterOp;
+  value: unknown;
 };
 
 /**
- * Logical group types for filter groups.
+ * Logical group types for filter groups. No "and" (top-level filters are
+ * already AND'd) and no nesting: the backend only parses one flat level.
  */
-export type LogicalGroupType = 'or' | 'and' | 'not';
+export type LogicalGroupType = 'or' | 'not';
 
 /**
- * Recursive filter group type: either a simple filter or a logical group of filters.
+ * A filter group is either a single attribute filter, or a logical group of
+ * flat (non-nested) attribute filters.
  */
 export type FilterGroup<T> =
   | { type: 'simple'; filter: SimpleFilter<T> }
-  | { type: LogicalGroupType; filters: FilterGroup<T>[] };
+  | { type: LogicalGroupType; filters: SimpleFilter<T>[] };
diff --git a/clients/typescript/src/types/jsonapi.ts b/clients/typescript/src/types/jsonapi.ts
index c15e88b..cbf5c5d 100644
--- a/clients/typescript/src/types/jsonapi.ts
+++ b/clients/typescript/src/types/jsonapi.ts
@@ -1,5 +1,6 @@
-// deno-lint-ignore-file no-explicit-any
-export interface JsonApiResource<T = any> {
+export type JsonApiAttributes = Record<string, unknown>;
+
+export interface JsonApiResource<T = JsonApiAttributes> {
   id: string;
   type: string;
   attributes: T;
@@ -12,21 +13,25 @@ export type JsonApiRelationship =
   | { data: Array<{ id: string; type: string }> }
   | { data: null };
 
-export interface JsonApiSingleResponse<T = any> {
+export type JsonApiMeta = Record<string, unknown> & {
+  pagination?: JsonApiPaginationMeta;
+};
+
+export interface JsonApiSingleResponse<T = JsonApiAttributes> {
   data: JsonApiResource<T>;
   included?: JsonApiResource[];
-  meta?: { pagination?: JsonApiPaginationMeta };
+  meta?: JsonApiMeta;
   links?: JsonApiLinks;
 }
 
-export interface JsonApiArrayResponse<T = any> {
+export interface JsonApiArrayResponse<T = JsonApiAttributes> {
   data: JsonApiResource<T>[];
   included?: JsonApiResource[];
-  meta?: { pagination?: JsonApiPaginationMeta };
+  meta?: JsonApiMeta;
   links?: JsonApiLinks;
 }
 
-export type JsonApiResponse<T = any> =
+export type JsonApiResponse<T = JsonApiAttributes> =
   | JsonApiSingleResponse<T>
   | JsonApiArrayResponse<T>;
 
@@ -47,26 +52,40 @@ export interface JsonApiLinks {
 }
 
 /**
- * Type for hydrated single resource result.
+ * Runtime shape of one resource, emitted by `dotnet jsonapi-typegen` next to
+ * the interface it describes. Lets hydration be honest about what the wire
+ * omits: null-stripped attributes become `null`, un-included relationships
+ * become `null` (to-one) or `[]` (to-many). Names are checked against `T`,
+ * so a stale generated file fails to compile.
  */
-export interface HydratedSingleResult<T> {
+export interface JsonApiResourceDescriptor<T>
+  extends JsonApiResourceDescriptorBase {
+  readonly attributes: readonly (keyof T & string)[];
+  readonly toOne: readonly (keyof T & string)[];
+  readonly toMany: readonly (keyof T & string)[];
+}
+
+/** Untyped form of {@link JsonApiResourceDescriptor}, for registries. */
+export interface JsonApiResourceDescriptorBase {
+  /** Wire `type`, also the default collection path. */
+  readonly type: string;
+  readonly attributes: readonly string[];
+  readonly toOne: readonly string[];
+  readonly toMany: readonly string[];
+}
+
+/** Descriptors keyed by wire type, for resolving included resources. */
+export type JsonApiResourceDescriptors = Record<
+  string,
+  JsonApiResourceDescriptorBase
+>;
+
+export interface HydratedSingle<T> {
   data: T;
-  meta?: { pagination?: JsonApiPaginationMeta };
-  links?: JsonApiLinks;
 }
 
-/**
- * Type for hydrated array resource result.
- */
-export interface HydratedArrayResult<T> {
+export interface HydratedList<T> {
   data: T[];
-  meta?: { pagination?: JsonApiPaginationMeta };
-  links?: JsonApiLinks;
+  /** Present only when the request was paginated (any `page[...]` param). */
+  pagination?: JsonApiPaginationMeta;
 }
-
-/**
- * Union type for hydrated query result.
- */
-export type HydratedQueryResult<T> =
-  | HydratedSingleResult<T>
-  | HydratedArrayResult<T>;
diff --git a/clients/typescript/src/types/query-builder.ts b/clients/typescript/src/types/query-builder.ts
index 6092569..27b96f5 100644
--- a/clients/typescript/src/types/query-builder.ts
+++ b/clients/typescript/src/types/query-builder.ts
@@ -18,38 +18,51 @@ export type Primitive =
 type StringKeys<T> = Extract<keyof T, string>;
 
 /**
- * Extracts keys from T whose values are primitives (attributes),
- * but excludes "id" and "type".
+ * Attribute values: primitives and primitive arrays (JSON columns).
+ * Nullability is stripped first, so `string | null` classifies as `string`.
+ */
+type IsAttribute<V> = NonNullable<V> extends Primitive | Primitive[] ? true
+  : false;
+
+/**
+ * Extracts keys from T whose values are attributes, excluding "id" and "type".
  */
 export type DirectAttributeKeys<T> = Exclude<
   {
-    [K in StringKeys<T>]: T[K] extends Primitive ? K : never;
+    [K in StringKeys<T>]: IsAttribute<T[K]> extends true ? K : never;
   }[StringKeys<T>],
   'id' | 'type'
 >;
 
 /**
- * Extract keys from T whose values are objects or arrays (relationships).
+ * Extracts keys from T whose values are objects or object arrays
+ * (relationships). `User | null` and optional properties count.
  */
 export type RelationshipKeys<T> = {
-  [K in StringKeys<T>]: T[K] extends Array<unknown> | object
-    ? (T[K] extends Primitive ? never : K)
+  [K in StringKeys<T>]: IsAttribute<T[K]> extends true ? never
+    : NonNullable<T[K]> extends object ? K
     : never;
 }[StringKeys<T>];
 
 /**
- * Extracts primitive attributes from a relationship type (excluding arrays).
+ * Extracts attributes from a to-one relationship's type (to-many yields none).
  */
-type RelationshipAttributeKeys<T, R extends keyof T> = T[R] extends
-  Array<unknown> ? never
-  : T[R] extends object ? Exclude<
-      {
-        [K in StringKeys<T[R]>]: T[R][K] extends Primitive ? K : never;
-      }[StringKeys<T[R]>],
-      'id' | 'type'
-    >
+type RelationshipAttributeKeys<T, R extends keyof T> = NonNullable<
+  T[R]
+> extends Array<unknown> ? never
+  : NonNullable<T[R]> extends object ? DirectAttributeKeys<NonNullable<T[R]>>
   : never;
 
+/**
+ * Direct attribute keys of a relationship's target type, whether the
+ * relationship is to-one or to-many. Used for `filterIncluded()`, which
+ * (unlike dot-path filtering) reaches through to-many relationships too.
+ */
+export type IncludedAttributeKeys<T, R extends RelationshipKeys<T>> =
+  DirectAttributeKeys<
+    NonNullable<T[R]> extends Array<infer E> ? E : NonNullable<T[R]>
+  >;
+
 /**
  * Nested relationship attribute keys in the format "relationship.attribute".
  */
@@ -60,12 +73,34 @@ type NestedAttributeKeys<T> = {
 }[RelationshipKeys<T>];
 
 /**
- * Combined attribute keys: direct attributes + nested relationship attributes.
+ * Escape hatch for filter paths deeper than one relationship level, e.g.
+ * "comments.author.name" (a to-many relationship's to-one relationship's
+ * attribute). The backend walks dot-paths up to a recursion guard
+ * (`FilterExpressionComposer.MaxRecursionDepth`, 5 segments) and goes
+ * through to-many relationships via `Any()`; modeling every reachable
+ * path at the type level isn't worth it, so only the first segment (a
+ * real relationship on `T`) is checked. Everything past the first dot is
+ * unverified at compile time; a typo two levels deep is a runtime 200
+ * with the filter silently ignored (or a 400 in strict mode), not a
+ * compile error.
+ */
+type DeepAttributeKeys<T> = {
+  [R in RelationshipKeys<T>]: `${R}.${string}.${string}`;
+}[RelationshipKeys<T>];
+
+/**
+ * Combined attribute keys: direct attributes, one typed level of nested
+ * relationship attributes, and the deep-path escape hatch above.
  */
-export type AttributeKeys<T> = DirectAttributeKeys<T> | NestedAttributeKeys<T>;
+export type AttributeKeys<T> =
+  | DirectAttributeKeys<T>
+  | NestedAttributeKeys<T>
+  | DeepAttributeKeys<T>;
 
 /**
- * Supported JSON:API filter operators.
+ * Supported JSON:API filter operators for `filter(field, op, value)`.
+ * Excludes `isnull`/`isnotnull`: use `filterNull()`/`filterNotNull()` instead,
+ * since those operators ignore the filter value entirely on the wire.
  */
 export type FilterOp =
   | 'eq' // equal
@@ -76,14 +111,25 @@ export type FilterOp =
   | 'le' // less than or equal
   | 'like' // like
   | 'in' // in
-  | 'nin' // not in
-  | 'isnull' // is null
-  | 'isnotnull'; // is not null
+  | 'nin'; // not in
 
 /**
- * Sort type for a JSON:API resource.
+ * The full set of operators the wire accepts, including the null checks.
+ * Internal: `SimpleFilter` needs this so `filterNull()`/`filterNotNull()`
+ * can construct a valid filter; the public `filter()` op param stays
+ * narrowed to `FilterOp`.
  */
-export type Sort<T> = Array<AttributeKeys<T> | `-${AttributeKeys<T>}`>;
+export type WireFilterOp = FilterOp | 'isnull' | 'isnotnull';
+
+/**
+ * Sort type for a JSON:API resource. Direct attributes only: the backend
+ * silently ignores a dot-path sort field (unlike filters, which do walk
+ * relationships), so `AttributeKeys<T>` would let a compiling call do
+ * nothing on the wire.
+ */
+export type Sort<T> = Array<
+  DirectAttributeKeys<T> | `-${DirectAttributeKeys<T>}`
+>;
 
 /**
  * Include type for a JSON:API resource (supports dot notation for nested relationships).
diff --git a/clients/typescript/src/types/query-builder_test.ts b/clients/typescript/src/types/query-builder_test.ts
new file mode 100644
index 0000000..ec09326
--- /dev/null
+++ b/clients/typescript/src/types/query-builder_test.ts
@@ -0,0 +1,47 @@
+/**
+ * Type-level probes for the key helpers. There is nothing to run; a wrong
+ * classification fails `deno check`. Each probe pairs a positive assignment
+ * with a `@ts-expect-error` negative so both directions are pinned.
+ */
+import type { AttributeKeys, RelationshipKeys } from './query-builder.ts';
+
+type Author = { id: string; name: string; email: string | null };
+type Article = {
+  id: string;
+  title: string;
+  publishedAt: string | null;
+  tags: string[];
+  author: Author | null;
+  editor?: Author;
+  comments: { id: string; text: string; author: Author }[];
+};
+
+// Nullable and optional relationships are relationships.
+const author: RelationshipKeys<Article> = 'author';
+const editor: RelationshipKeys<Article> = 'editor';
+const comments: RelationshipKeys<Article> = 'comments';
+// @ts-expect-error a primitive array is an attribute, not a relationship
+const tags: RelationshipKeys<Article> = 'tags';
+
+// Nullable attributes and primitive arrays are attributes.
+const publishedAt: AttributeKeys<Article> = 'publishedAt';
+const tagsAttr: AttributeKeys<Article> = 'tags';
+// Nested attributes reach through nullable to-one relationships.
+const authorEmail: AttributeKeys<Article> = 'author.email';
+// @ts-expect-error id is never a filterable attribute
+const id: AttributeKeys<Article> = 'id';
+// @ts-expect-error to-many relationships do not expose nested attributes
+const commentText: AttributeKeys<Article> = 'comments.text';
+
+// Deep paths (2+ dots) are a checked-first-segment escape hatch: the
+// backend walks dot-paths through to-many relationships via Any(), which
+// the type helpers above don't model past one level.
+const deepPath: AttributeKeys<Article> = 'comments.author.name';
+// @ts-expect-error the first segment of a deep path must be a real relationship
+const deepPathBogusRelationship: AttributeKeys<Article> = 'bogus.author.name';
+
+Deno.test('type probes compile', () => {
+  void [author, editor, comments, tags, publishedAt, tagsAttr, authorEmail];
+  void [id, commentText];
+  void [deepPath, deepPathBogusRelationship];
+});
diff --git a/justfile b/justfile
index c0071a8..8ed60ec 100644
--- a/justfile
+++ b/justfile
@@ -126,7 +126,8 @@ typegen *args:
     dotnet build {{sample}} --configuration Release
     dotnet run --project JsonApiToolkit.TypeGen --configuration Release --no-build -- \
         --assembly {{sample}}/bin/Release/net10.0/ContractApi.dll \
-        --out {{sample}}/api-types.gen.ts {{args}}
+        --out {{sample}}/api-types.gen.ts \
+        --client-import ../../clients/typescript/src/index.ts {{args}}
 
 # Everything CI runs: format check, unit tests, the contract suite, and typegen drift
 [group('quality')]
diff --git a/samples/ContractApi/Program.cs b/samples/ContractApi/Program.cs
index 515e25d..01682ed 100644
--- a/samples/ContractApi/Program.cs
+++ b/samples/ContractApi/Program.cs
@@ -2,24 +2,23 @@
 using JsonApiToolkit.Extensions;
 using Microsoft.EntityFrameworkCore;
 
-var builder = WebApplication.CreateBuilder(args);
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
 
 builder.Services.AddDbContext<ContractDbContext>(o => o.UseInMemoryDatabase("contract-api"));
 builder.Services.AddControllers();
 builder.Services.AddJsonApiToolkit(o =>
 {
-    // Contract tests run one default instance and one instance with every
-    // opt-in behavior enabled.
     bool strict = builder.Configuration.GetValue<bool>("JSONAPI_STRICT");
     o.StrictPagination = strict;
     o.StrictQueryValidation = strict;
     o.PreserveQueryInPaginationLinks = strict;
+    o.UseResourceAttributeTypeNames = strict;
 });
 
-var app = builder.Build();
+WebApplication app = builder.Build();
 app.MapControllers();
 
-using (var scope = app.Services.CreateScope())
+using (IServiceScope scope = app.Services.CreateScope())
 {
     Seed.Run(scope.ServiceProvider.GetRequiredService<ContractDbContext>());
 }
diff --git a/samples/ContractApi/api-types.gen.ts b/samples/ContractApi/api-types.gen.ts
index 6f576d8..f9f59ca 100644
--- a/samples/ContractApi/api-types.gen.ts
+++ b/samples/ContractApi/api-types.gen.ts
@@ -1,4 +1,5 @@
 // AUTO-GENERATED by `dotnet jsonapi-typegen`. Do not edit by hand.
+import type { JsonApiResourceDescriptor } from "../../clients/typescript/src/index.ts";
 
 export interface Article {
   id: string;
@@ -13,12 +14,26 @@ export interface Article {
   comments: Comment[];
 }
 
+export const Article: JsonApiResourceDescriptor<Article> = {
+  type: "articles",
+  attributes: ["title", "body", "published", "publishedAt", "viewCount", "tags", "authorId"],
+  toOne: ["author"],
+  toMany: ["comments"],
+};
+
 export interface Author {
   id: string;
   name: string;
   email: string | null;
 }
 
+export const Author: JsonApiResourceDescriptor<Author> = {
+  type: "authors",
+  attributes: ["name", "email"],
+  toOne: [],
+  toMany: [],
+};
+
 export interface Comment {
   id: string;
   text: string;
@@ -29,8 +44,9 @@ export interface Comment {
   author: Author | null;
 }
 
-export const ResourceMap = {
-  Article: { type: "articles", relationships: ["author", "comments"] },
-  Author: { type: "authors", relationships: [] },
-  Comment: { type: "comments", relationships: ["article", "author"] },
-} as const;
+export const Comment: JsonApiResourceDescriptor<Comment> = {
+  type: "comments",
+  attributes: ["text", "createdAt", "articleId", "authorId"],
+  toOne: ["article", "author"],
+  toMany: [],
+};