@artu-ai/compliance-sdk 0.13.4 → 0.17.0

package/dist/resources/base.d.ts

@@ -4,20 +4,15 @@
  * Abstract base class for all resource managers.
  * Provides common patterns: validation, error mapping, pagination.
  */
-import type { IterateOptions, ListOptions, PaginatedResponse, Scope } from "@artu-ai/shared";
+import { type IterateOptions, type ListOptions, type PaginatedResponse, type Scope } from "@artu-ai/shared";
 import type { ZodType } from "zod";
 import type { Environment } from "../sdk/types";
-import type { TRPCClient } from "../utils/trpc-client";
 /**
  * Configuration for creating a resource manager
  */
 export interface ResourceConfig {
     /**
-     * tRPC client instance for API communication
-     */
-    trpc: TRPCClient;
-    /**
-     * Optional SDK scope for jurisdiction/activity scoping
+     * Optional SDK scope for scope/activity scoping
      */
     scope?: Scope;
     /**
@@ -60,21 +55,32 @@ export interface ResourceConfig {
  * ```
  */
 export declare abstract class BaseResource<TModel, TCreateInput, TUpdateInput, TFilter = Record<string, unknown>, TSort = unknown, TCreateResult = TModel> {
-    /**
-     * tRPC client for API communication
-     */
-    protected readonly trpc: TRPCClient;
     /**
      * SDK scope
      */
     protected readonly scope: Scope | undefined;
+    /**
+     * Which filter key carries this resource's scope, enabling auto-scoping.
+     * - "scopes": resource has a scope-array column and is auto-scoped
+     *   (clients, transactions, products).
+     * - "scope": resource has a single scope column and is auto-scoped (alerts).
+     * - null (default): auto-scoping is skipped.
+     *
+     * Only resources that are independently scope-partitioned set this. Notably
+     * addresses and bank-accounts have scope columns but are intentionally left
+     * `null` — they're owned by a parent client/transaction and aren't queried
+     * by scope on their own (see the auto-scope design doc).
+     *
+     * Set on each auto-scoped resource's base class; inherited by scoped subclasses.
+     */
+    protected scopeFilterKey: "scope" | "scopes" | null;
     /**
      * Whether client-side postal code format validation is enabled
      */
     protected readonly enablePostalCodeValidation: boolean;
     constructor(config: ResourceConfig);
     /**
-     * Whether this resource is scoped to a jurisdiction
+     * Whether this resource is scoped to a scope
      */
     protected get isScoped(): boolean;
     /**
@@ -134,6 +140,35 @@ export declare abstract class BaseResource<TModel, TCreateInput, TUpdateInput, T
      * ```
      */
     protected validate<T>(schema: ZodType<T>, data: unknown): T;
+    /**
+     * Returns this SDK instance's scope plus all descendant scopes.
+     * Empty when the SDK is unscoped (base SDK).
+     */
+    protected expandScope(): Scope[];
+    /**
+     * Injects this resource's scope filter into `filter`, enforcing strict
+     * scoping. Behaviour:
+     * - unscoped SDK, `scopeFilterKey === null`, or `crossScope === true`:
+     *   returns `filter` unchanged.
+     * - user already set the scope key: throws `ScopeViolationError` (unless
+     *   `crossScope` is true, in which case their value is preserved).
+     * - otherwise: returns `filter` with `{ [scopeFilterKey]: { in: expandScope() } }`.
+     *
+     * NOTE: this is a client-side convenience, not a server-enforced
+     * authorization boundary. The injected filter is an ordinary query filter
+     * the server applies like any other; a raw API call to `list`/`count`
+     * without it still returns every record the API key can read. The real
+     * isolation boundary remains organization + environment + RLS. (Retrieve*
+     * calls additionally pass `requireScope` so the server hard-scopes single
+     * lookups — see {@link buildRequireScope}.)
+     */
+    protected applyAutoScope<TFilterArg extends Record<string, unknown>>(filter: TFilterArg | undefined, crossScope: boolean | undefined): TFilterArg | undefined;
+    /**
+     * Builds the `requireScope` argument for retrieve* calls.
+     * Returns the expanded scopes, or `undefined` when unscoped, when the
+     * resource has no scope column, or when `crossScope` is true.
+     */
+    protected buildRequireScope(crossScope: boolean | undefined): Scope[] | undefined;
     /**
      * Wraps a tRPC operation with error mapping.
      * Converts tRPC errors to SDK-specific errors.
@@ -165,7 +200,9 @@ export declare abstract class BaseResource<TModel, TCreateInput, TUpdateInput, T
      * }
      * ```
      */
-    protected createIterator<T = TModel>(options?: IterateOptions<TFilter, TSort>): AsyncGenerator<T, void, undefined>;
+    protected createIterator<T = TModel>(options?: IterateOptions<TFilter, TSort> & {
+        crossScope?: boolean;
+    }): AsyncGenerator<T, void, undefined>;
 }
 /**
  * Base class for read-only resources (no create/update/delete).
@@ -176,7 +213,6 @@ export declare abstract class BaseResource<TModel, TCreateInput, TUpdateInput, T
  * @typeParam TSort - Sort type for list operations
  */
 export declare abstract class ReadOnlyResource<TModel, TFilter = Record<string, unknown>, TSort = unknown> {
-    protected readonly trpc: TRPCClient;
     constructor(config: ResourceConfig);
     /**
      * Retrieves a resource by ID
@@ -197,6 +233,7 @@ export declare abstract class ReadOnlyResource<TModel, TFilter = Record<string,
     /**
      * Creates an async iterator for paginated results
      */
-    protected createIterator<T = TModel>(options?: IterateOptions<TFilter, TSort>): AsyncGenerator<T, void, undefined>;
+    protected createIterator<T = TModel>(options?: IterateOptions<TFilter, TSort> & {
+        crossScope?: boolean;
+    }): AsyncGenerator<T, void, undefined>;
 }
-//# sourceMappingURL=base.d.ts.map

package/dist/resources/base.js

@@ -4,8 +4,9 @@
  * Abstract base class for all resource managers.
  * Provides common patterns: validation, error mapping, pagination.
  */
+import { Scopes, } from "@artu-ai/shared";
 import { TRPCClientError } from "@trpc/client";
-import { mapTRPCError, ValidationError } from "../errors";
+import { mapTRPCError, ScopeViolationError, ValidationError } from "../errors";
 import { createPaginatedIterator } from "../utils/pagination";
 /**
  * Type guard for tRPC client errors
@@ -50,12 +51,28 @@ function isTRPCError(error) {
 export class BaseResource {
     /**
      * tRPC client for API communication
+     * @internal
      */
     trpc;
     /**
      * SDK scope
      */
     scope;
+    /**
+     * Which filter key carries this resource's scope, enabling auto-scoping.
+     * - "scopes": resource has a scope-array column and is auto-scoped
+     *   (clients, transactions, products).
+     * - "scope": resource has a single scope column and is auto-scoped (alerts).
+     * - null (default): auto-scoping is skipped.
+     *
+     * Only resources that are independently scope-partitioned set this. Notably
+     * addresses and bank-accounts have scope columns but are intentionally left
+     * `null` — they're owned by a parent client/transaction and aren't queried
+     * by scope on their own (see the auto-scope design doc).
+     *
+     * Set on each auto-scoped resource's base class; inherited by scoped subclasses.
+     */
+    scopeFilterKey = null;
     /**
      * Whether client-side postal code format validation is enabled
      */
@@ -67,7 +84,7 @@ export class BaseResource {
             config.enablePostalCodeValidation ?? false;
     }
     /**
-     * Whether this resource is scoped to a jurisdiction
+     * Whether this resource is scoped to a scope
      */
     get isScoped() {
         return this.scope !== undefined;
@@ -104,6 +121,59 @@ export class BaseResource {
         }
         return result.data;
     }
+    /**
+     * Returns this SDK instance's scope plus all descendant scopes.
+     * Empty when the SDK is unscoped (base SDK).
+     */
+    expandScope() {
+        // "base" means "all data" — treat it like unscoped (no auto-filter).
+        if (!this.scope || this.scope === "base")
+            return [];
+        return Scopes.getDescendants(this.scope);
+    }
+    /**
+     * Injects this resource's scope filter into `filter`, enforcing strict
+     * scoping. Behaviour:
+     * - unscoped SDK, `scopeFilterKey === null`, or `crossScope === true`:
+     *   returns `filter` unchanged.
+     * - user already set the scope key: throws `ScopeViolationError` (unless
+     *   `crossScope` is true, in which case their value is preserved).
+     * - otherwise: returns `filter` with `{ [scopeFilterKey]: { in: expandScope() } }`.
+     *
+     * NOTE: this is a client-side convenience, not a server-enforced
+     * authorization boundary. The injected filter is an ordinary query filter
+     * the server applies like any other; a raw API call to `list`/`count`
+     * without it still returns every record the API key can read. The real
+     * isolation boundary remains organization + environment + RLS. (Retrieve*
+     * calls additionally pass `requireScope` so the server hard-scopes single
+     * lookups — see {@link buildRequireScope}.)
+     */
+    applyAutoScope(filter, crossScope) {
+        const key = this.scopeFilterKey;
+        const expanded = this.expandScope();
+        // Nothing to inject: unscoped, no scope column, or explicit opt-out.
+        if (key === null || expanded.length === 0 || crossScope) {
+            return filter;
+        }
+        if (filter && filter[key] !== undefined) {
+            throw new ScopeViolationError(this.scope, key);
+        }
+        return {
+            ...(filter ?? {}),
+            [key]: { in: expanded },
+        };
+    }
+    /**
+     * Builds the `requireScope` argument for retrieve* calls.
+     * Returns the expanded scopes, or `undefined` when unscoped, when the
+     * resource has no scope column, or when `crossScope` is true.
+     */
+    buildRequireScope(crossScope) {
+        if (this.scopeFilterKey === null || crossScope)
+            return undefined;
+        const expanded = this.expandScope();
+        return expanded.length > 0 ? expanded : undefined;
+    }
     /**
      * Wraps a tRPC operation with error mapping.
      * Converts tRPC errors to SDK-specific errors.
@@ -149,6 +219,7 @@ export class BaseResource {
         return createPaginatedIterator((pagination) => this.list({
             filter: options?.filter,
             sort: options?.sort,
+            crossScope: options?.crossScope,
             ...pagination,
         }), { limit: options?.pageSize });
     }
@@ -165,6 +236,7 @@ export class BaseResource {
  * @typeParam TSort - Sort type for list operations
  */
 export class ReadOnlyResource {
+    /** @internal */
     trpc;
     constructor(config) {
         this.trpc = config.trpc;
@@ -190,6 +262,7 @@ export class ReadOnlyResource {
         return createPaginatedIterator((pagination) => this.list({
             filter: options?.filter,
             sort: options?.sort,
+            crossScope: options?.crossScope,
             ...pagination,
         }), { limit: options?.pageSize });
     }

package/dist/resources/clients.d.ts

@@ -3,15 +3,17 @@
  *
  * CRUD operations, filtering, pagination, and batch operations for clients.
  *
- * This is the base (unscoped) resource. For jurisdiction-scoped SDKs, use:
+ * This is the base (unscoped) resource. For scope-scoped SDKs, use:
  * - MexClientsResource - Mexico-scoped with flattened MX fields
  * - AVIClientsResource - Mexico AVI-scoped with flattened AVI fields
  * - JYSClientsResource - Mexico JYS-scoped with flattened JYS fields
  * - TSCClientsResource - Mexico TSC-scoped with flattened TSC fields
  */
-import type { AtomicBatchResult, ClientFilter, ClientRelationshipType, ClientSort, CreateAddressInput, CreateBankAccountInput, CreateClientInput, CreateContactMethodInput, LinkedClient as LinkedClientInput, ListOptions, PaginatedResponse, PartialBatchResult, ResourceTagResponse, RiskAssessmentInfo, SyncCreateDocumentInput, SyncItem, SyncResult, SyncUpdateDocumentInput, UpdateAddressInput, UpdateBankAccountInput, UpdateClientInput, UpdateContactMethodInput, UpsertClientInput, UpsertResult } from "@artu-ai/shared";
+import type { AtomicBatchResult, Checklist, ClientFilter, ClientRelationshipType, ClientSort, CreateAddressInput, CreateBankAccountInput, CreateClientInput, CreateContactMethodInput, LinkedClient as LinkedClientInput, ListOptions, MigrationPreview, MigrationResult, migrateClientInputSchema, PaginatedResponse, PartialBatchResult, ResourceTagResponse, RiskAssessmentInfo, Scope, SyncCreateDocumentInput, SyncItem, SyncLinkedClientInput, SyncResult, SyncUpdateDocumentInput, UpdateAddressInput, UpdateBankAccountInput, UpdateClientInput, UpdateContactMethodInput, UpsertClientInput, UpsertResult } from "@artu-ai/shared";
+import { z } from "zod";
 import { Address, BankAccount, Client, type ClientData, ContactMethod, Document, LinkedClient } from "../models";
-import { BaseResource } from "./base";
+import { BaseResource, type ResourceConfig } from "./base";
+import { type RelatedPartyParent, type RelatedPartySubresource } from "./related-parties/base";
 /**
  * Options for batch operations
  */
@@ -30,6 +32,11 @@ export interface ClientIncludeMap {
     documents?: boolean;
     linkedClients?: boolean;
 }
+/**
+ * Options for `clients.migrate` / `clients.migratePreview`. The source-row
+ * `id` is supplied as the first argument, so it is omitted here.
+ */
+export type MigrateClientOptions = Omit<z.input<typeof migrateClientInputSchema>, "id">;
 /**
  * Base resource manager for client operations.
  *
@@ -45,7 +52,7 @@ export interface ClientIncludeMap {
  *   type: "individual",
  *   name: "Juan García",
  *   scopes: ["MX"],
- *   jurisdictions: {
+ *   scopeData: {
  *     MX: { rfc: "GAJL850101ABC" },
  *   },
  * });
@@ -63,6 +70,56 @@ export interface ClientIncludeMap {
  * ```
  */
 export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Client, CreateClientInput, UpdateClientInput, ClientFilter, TSort> {
+    protected scopeFilterKey: "scope" | "scopes" | null;
+    /**
+     * Typed subresource for legal representatives. A legal rep is a
+     * non-primary client linked to a parent client via the
+     * `legal_representative` relationship type.
+     *
+     * ```ts
+     * await sdk.clients.legalRepresentatives.create(companyId, {
+     *   type: "individual",
+     *   name: "Juan García",
+     *   scopes: ["MX"],
+     *   scopeData: { MX: { rfc: "GAJL850101ABC" } },
+     * });
+     * ```
+     */
+    readonly legalRepresentatives: RelatedPartySubresource<Client, CreateClientInput>;
+    /**
+     * Typed subresource for controlling beneficiaries. A controlling beneficiary
+     * is a non-primary client linked to a parent client via the
+     * `controlling_beneficiary` relationship type.
+     */
+    readonly controllingBeneficiaries: RelatedPartySubresource<Client, CreateClientInput>;
+    constructor(config: ResourceConfig);
+    /**
+     * Wires the typed subresources (`legalRepresentatives`,
+     * `controllingBeneficiaries`) to this resource's methods. Scoped
+     * subclasses override this so their typed subresources get scope-narrowed
+     * input/output types. Method dispatch resolves at call time, so the
+     * factory called in the base constructor still picks up subclass
+     * overrides.
+     */
+    protected relatedPartyParent(): RelatedPartyParent<Client, CreateClientInput>;
+    /**
+     * Creates a non-primary client and links it to a parent client in one
+     * atomic call, with the relationship type chosen at call time. Use this
+     * when the type is dynamic (e.g. UI flows that show a relationship-type
+     * picker). When the type is fixed, prefer the typed subresources
+     * (`legalRepresentatives.create`, `controllingBeneficiaries.create`).
+     */
+    createRelatedClient(parentClientId: string, relationshipType: ClientRelationshipType, input: CreateClientInput, metadata?: Record<string, unknown>): Promise<import("./related-parties/base").RelatedPartyCreateResult<Client>>;
+    /**
+     * Builds a `RelatedPartyParent` for the typed subresources. Scoped
+     * subclasses pass a `prepareChild` function that validates and (if
+     * needed) transforms the scope-specific input into the base
+     * `CreateClientInput` shape before it reaches the API. All other plumbing
+     * (instantiate, list/retrieve/update/unlink) reuses the dynamically
+     * dispatched methods on `this` so subclasses get the right model types
+     * for free.
+     */
+    protected makeRelatedPartyParent<TClient extends Client, TCreateInput>(prepareChild: (input: TCreateInput) => CreateClientInput): RelatedPartyParent<TClient, TCreateInput>;
     /**
      * Creates a new client.
      *
@@ -75,7 +132,7 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      *   type: ClientType.Person,
      *   name: "Juan García",
      *   scopes: ["MX"],
-     *   jurisdictions: {
+     *   scopeData: {
      *     MX: { rfc: "GAJL850101ABC" },
      *   },
      * });
@@ -86,14 +143,47 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      * Retrieves a client by ID.
      *
      * @param id - Client ID
-     * @param include - Optional includes (relations, primary contacts)
+     * @param options - Optional retrieve options:
+     *   - `include`: relations / primary contacts to populate
+     *   - `crossScope`: skip this scoped SDK's scope enforcement
      * @returns The client model (with optional fields populated if included)
      */
-    retrieve(id: string, include?: ClientIncludeMap): Promise<Client>;
+    retrieve(id: string, options?: {
+        include?: ClientIncludeMap;
+        crossScope?: boolean;
+    }): Promise<Client>;
+    /**
+     * Retrieves the raw, un-instantiated client payload by ID.
+     *
+     * The API call is identical across every scope; only the client-side
+     * reshape differs. The React SDK caches this single scope-agnostic payload
+     * and lets each scope derive its own shape via `materialize`, avoiding N
+     * redundant fetches in nested scope-overview components.
+     *
+     * Unlike `retrieve`/`retrieveByMetadata`/`retrieveByExternalId`, this method
+     * intentionally does NOT pass `requireScope`, and that is safe: `requireScope`
+     * is a client-supplied OPTIONAL narrowing filter, never the authorization
+     * boundary. Tenant isolation (organization + environment) is enforced
+     * server-side by row-level security on the request's tenant context and
+     * applies identically here — `retrieveRaw` hits the very same
+     * `clients.retrieve` endpoint. Omitting `requireScope` only declines to
+     * narrow to a sub-scope (AVI vs CNBV, etc.), which the caller can already do
+     * via the base SDK or `crossScope: true`; it cannot expose another tenant's
+     * data. This is required for the dedup: the payload is keyed by id alone and
+     * fetched once for all scopes, so a per-scope filter would leak one scope's
+     * narrowing onto every other scope sharing the cache entry.
+     *
+     * @param id - Client ID
+     * @param include - Optional includes (relations, primary contacts)
+     * @returns The raw API payload (`ClientData`) — not a model instance
+     */
+    retrieveRaw(id: string, include?: ClientIncludeMap): Promise<ClientData>;
     /**
      * Retrieves a client by metadata key/value.
      */
-    retrieveByMetadata(key: string, value: string): Promise<Client>;
+    retrieveByMetadata(key: string, value: string, opts?: {
+        crossScope?: boolean;
+    }): Promise<Client>;
     /**
      * Retrieves a client by externalId.
      *
@@ -106,7 +196,28 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      * console.log(client.name);
      * ```
      */
-    retrieveByExternalId(externalId: string): Promise<Client>;
+    retrieveByExternalId(externalId: string, opts?: {
+        crossScope?: boolean;
+    }): Promise<Client>;
+    /**
+     * Get the compliance checklist for a client in a given scope.
+     *
+     * The checklist lists per-field, per-resource compliance items that
+     * indicate what is missing or invalid for the client to be ready under
+     * the requested scope. Items can be scoped to specific levels via
+     * `levels` (omitted = required by every level the scope declares);
+     * per-level completeness is in `complete`.
+     *
+     * @param id - The client's UUID
+     * @param opts.scope - The scope to evaluate (e.g., "MX:AV:AVI")
+     * @param opts.includeChildren - When true, rollup items include
+     *   per-child item arrays. Defaults to true; pass false to receive
+     *   only the rollup summaries (useful for list views).
+     */
+    checklist(id: string, opts: {
+        scope: Scope;
+        includeChildren?: boolean;
+    }): Promise<Checklist>;
     /**
      * Updates a client.
      *
@@ -156,11 +267,21 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      */
     list(options?: ListOptions<ClientFilter, TSort> & {
         includePrimaryContacts?: boolean;
+        /**
+         * When true, includes non-primary clients (legal reps, controlling
+         * beneficiaries) in the results. Default behavior filters to
+         * primary clients only.
+         */
+        includeNonPrimary?: boolean;
+        crossScope?: boolean;
     }): Promise<PaginatedResponse<Client>>;
     /**
      * Counts clients matching the given filter.
      *
      * @param filter - Optional filter criteria
+     * @param options - Optional flags
+     * @param options.includeNonPrimary - When true, counts non-primary
+     *   clients as well. Defaults to primary-only.
      * @returns The count of matching clients
      *
      * @example
@@ -169,7 +290,52 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      * console.log(`Found ${count} individual clients`);
      * ```
      */
-    count(filter?: ClientFilter): Promise<number>;
+    count(filter?: ClientFilter, options?: {
+        includeNonPrimary?: boolean;
+        crossScope?: boolean;
+    }): Promise<number>;
+    /**
+     * Promotes a non-primary client (a rep or BO created via a typed
+     * subresource) to a primary client. Idempotent — calling on an
+     * already-primary client returns the existing client unchanged.
+     *
+     * @param id - Client ID to promote
+     * @returns The (now-primary) client model
+     */
+    promote(id: string): Promise<Client>;
+    /**
+     * Copies this client into the other environment (test ↔ live), upserting it
+     * and the selected subresources by externalId.
+     *
+     * The whole graph is migrated atomically: nothing is written unless every
+     * resource can be matched by externalId. When any resource in the graph
+     * lacks an externalId the call throws {@link MigrationBlockedError} (whose
+     * `blockers` lists the offending resources) and nothing is written — assign
+     * the missing externalIds and retry.
+     *
+     * @param id - Source-environment client id
+     * @param options - Target environment, precedence, and subresource selection
+     * @returns The completed migration result (target id, action, per-resource counts)
+     * @throws {MigrationBlockedError} when resources in the graph lack an externalId
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.clients.migrate(clientId, { to: "live" });
+     * console.log(result.action, result.targetId);
+     * ```
+     */
+    migrate(id: string, options: MigrateClientOptions): Promise<Extract<MigrationResult, {
+        status: "completed";
+    }>>;
+    /**
+     * Dry-run of {@link migrate}: reports what would be created/updated in the
+     * target environment and any blockers, without writing anything.
+     *
+     * @param id - Source-environment client id
+     * @param options - Target environment, precedence, and subresource selection
+     * @returns The migration preview (target action, blockers, per-resource counts)
+     */
+    migratePreview(id: string, options: MigrateClientOptions): Promise<MigrationPreview>;
     /**
      * Returns distinct risk assessment names and their display settings.
      *
@@ -195,6 +361,7 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
         filter?: ClientFilter;
         sort?: TSort;
         pageSize?: number;
+        crossScope?: boolean;
     }): AsyncGenerator<Client, void, undefined>;
     /**
      * Creates multiple clients in a single request.
@@ -480,7 +647,7 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
         contactMethods?: SyncItem<CreateContactMethodInput>[];
         bankAccounts?: SyncItem<CreateBankAccountInput>[];
         documents?: SyncItem<SyncCreateDocumentInput>[];
-        linkedClients?: LinkedClientInput[];
+        linkedClients?: SyncLinkedClientInput[];
     }, options?: {
         replaceMode?: boolean;
     }): Promise<{
@@ -496,7 +663,7 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
         contactMethods?: SyncItem<CreateContactMethodInput>[];
         bankAccounts?: SyncItem<CreateBankAccountInput>[];
         documents?: SyncItem<SyncCreateDocumentInput>[];
-        linkedClients?: LinkedClientInput[];
+        linkedClients?: SyncLinkedClientInput[];
     }, options: {
         replaceMode: true;
     }): Promise<{
@@ -512,7 +679,7 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
         contactMethods?: SyncItem<UpdateContactMethodInput>[];
         bankAccounts?: SyncItem<UpdateBankAccountInput>[];
         documents?: SyncItem<SyncUpdateDocumentInput>[];
-        linkedClients?: LinkedClientInput[];
+        linkedClients?: SyncLinkedClientInput[];
     }, options?: {
         replaceMode?: boolean;
     }): Promise<{
@@ -543,5 +710,13 @@ export declare class ClientsResource<TSort = ClientSort> extends BaseResource<Cl
      * Subclasses override this to return their specific model type.
      */
     protected instantiate(data: ClientData): Client;
+    /**
+     * Public, pure transform from a raw client payload to this scope's model.
+     *
+     * Wraps the protected `instantiate` so the React SDK can apply it inside a
+     * TanStack Query `select`. Subclasses override `instantiate` (and override
+     * `materialize` to narrow the return type), so each scope automatically
+     * materializes its own model type.
+     */
+    materialize(data: ClientData): Client;
 }
-//# sourceMappingURL=clients.d.ts.map