@stonecrop/graphql-client 0.11.0 → 0.11.2

package/dist/index.js

@@ -1,62 +1 @@
-import { Decimal } from 'decimal.js';
-import { GraphQLClient } from 'graphql-request';
-import { queries } from './queries';
-import typeDefs from './gql/schema';
-/**
- * Parse the response from the GraphQL server. Converts the stringified JSON to JSON and converts the stringified numbers to Decimal.
- * @param obj - The response from the GraphQL server
- * @returns The parsed response
- * @example
- * const response = '{"data":{"getMeta":{"id":"Issue","name":"Issue","workflow":"{\"machineId\":null,\"name\":\"save\",\"id\":\"1\"}","schema":"[{\"label\":\"Subject\",\"id\":\"1\"}]","actions":"[{\"eventName\":\"save\",\"id\":\"1\"}]"}}}'
- * const parsedResponse = metaParser(response)
- * console.log(parsedResponse)
- * /* Output: {"id": "Issue", "name": "Issue", "workflow": { "machineId": null, "name": "save", "id": "1" }, "schema": [{ "label": "Subject", "id": "1" }], "actions": [{ "eventName": "save", "id": "1" }]}
- */
-const metaParser = (obj) => {
-    return JSON.parse(obj, (key, value) => {
-        if (typeof value === 'string') {
-            try {
-                return JSON.parse(value, (_key, value) => {
-                    if (typeof value === 'string' && !isNaN(Number(value))) {
-                        return new Decimal(value);
-                    }
-                    return value;
-                });
-            }
-            catch {
-                // if the value is not a stringified JSON, return as it is
-                return value;
-            }
-        }
-        else if (!isNaN(Number(value))) {
-            return new Decimal(value);
-        }
-        return value;
-    });
-};
-/**
- * Get meta information for a doctype
- * @param doctype - The doctype to get meta information for
- * @param url - The URL to send the request to
- * @returns The meta information for the doctype
- * @public
- */
-const methods = {
-    getMeta: async (doctype, url) => {
-        const client = new GraphQLClient(url || '/graphql', {
-            fetch: window.fetch,
-            jsonSerializer: {
-                stringify: obj => JSON.stringify(obj), // process the request object before sending; leave as default JSON
-                parse: metaParser, // process the response meta object
-            },
-        });
-        const { getMeta } = await client.request({
-            document: queries.getMeta,
-            variables: { doctype },
-        });
-        return getMeta;
-    },
-};
-export { queries, typeDefs, methods };
 export { StonecropClient } from './client';
-export { buildRecordQuery, buildListQuery } from './query';

package/dist/src/client.d.ts

@@ -1,5 +1,7 @@
 import type { DataClient, DoctypeMeta, DoctypeContext, DoctypeRef, GetRecordOptions, GetRecordsOptions } from '@stonecrop/schema';
+import type { GetRecordResult } from './types';
 export type { DoctypeContext, DoctypeRef };
+export type { GetRecordResult };
 /**
  * Options for creating a Stonecrop client
  * @public
@@ -9,27 +11,31 @@ export interface StonecropClientOptions {
     endpoint: string;
     /** Additional HTTP headers to include in requests */
     headers?: Record<string, string>;
-    /** Doctype registry for nested query building */
-    registry?: Map<string, DoctypeMeta>;
 }
 /**
- * Client for interacting with Stonecrop GraphQL API
+ * Client for interacting with Stonecrop GraphQL API.
+ *
+ * Acts as a transport layer — it passes requests to the middleware and returns
+ * merged results. Does not construct queries itself.
+ *
  * @public
  */
 export declare class StonecropClient implements DataClient {
     private endpoint;
     private headers;
     private metaCache;
-    private registry?;
     constructor(options: StonecropClientOptions);
     /**
-     * Execute a GraphQL query
+     * Execute a GraphQL query against the configured endpoint.
+     *
      * @param query - GraphQL query string
      * @param variables - Query variables
+     * @throws Error if the GraphQL response contains errors
      */
     query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
     /**
-     * Execute a GraphQL mutation
+     * Execute a GraphQL mutation. Delegates to query() since both use POST.
+     *
      * @param mutation - GraphQL mutation string
      * @param variables - Mutation variables
      */
@@ -46,16 +52,20 @@ export declare class StonecropClient implements DataClient {
     /**
      * Get a single record by ID.
      *
-     * When `includeNested` is set, builds a query with sub-selections for descendant
-     * links and returns ancestor + merged descendants. When omitted, returns flat scalar data.
+     * Routes through the stonecropRecord resolver which handles nested data
+     * fetching based on the includeNested option.
      *
      * @param doctype - Doctype reference (name and optional slug)
      * @param recordId - Record ID to fetch
      * @param options - Query options (includeNested, maxDepth)
      */
-    getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<Record<string, unknown> | null>;
+    getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<GetRecordResult>;
     /**
-     * Get multiple records with optional filtering and pagination
+     * Get multiple records with optional filtering and pagination.
+     *
+     * Returns flat arrays — the middleware merges connection format (\{ nodes: [...] \})
+     * into plain arrays before returning.
+     *
      * @param doctype - Doctype reference (name and optional slug)
      * @param options - Query options (filters, orderBy, limit, offset)
      */
@@ -72,7 +82,10 @@ export declare class StonecropClient implements DataClient {
         error: string | null;
     }>;
     /**
-     * Clear the cached doctype metadata
+     * Clear the cached doctype metadata.
+     *
+     * Call this if the server-side doctype schema has changed and you need
+     * to fetch fresh metadata (e.g., after adding a new field).
      */
     clearMetaCache(): void;
 }

package/dist/src/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,mBAAmB,CAAA;AAM1B,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAe1C;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,iDAAiD;IACjD,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CACnC;AAED;;;GAGG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,QAAQ,CAAC,CAA0B;gBAE/B,OAAO,EAAE,sBAAsB;IAS3C;;;;OAIG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBxF;;;;OAIG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5F;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuDnE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAmD1C;;;;;;;;;OASG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACxB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IA8C1C;;;;OAIG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAiCtG;;;;;OAKG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EAAE,GACd,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAuBrE;;OAEG;IACH,cAAc,IAAI,IAAI;CAGtB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACtC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACjD,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAsC;gBAE3C,OAAO,EAAE,sBAAsB;IAQ3C;;;;;;OAMG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAmBxF;;;;;OAKG;IACG,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI5F;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAuDnE;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAmD1C;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA4B5G;;;;;;;;OAQG;IACG,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAiCtG;;;;;OAKG;IACG,SAAS,CACd,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EAAE,GACd,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAuBrE;;;;;OAKG;IACH,cAAc,IAAI,IAAI;CAGtB"}

package/dist/src/index.d.ts

@@ -1,20 +1,4 @@
-import { queries } from './queries';
-import typeDefs from './gql/schema';
-import type { MetaResponse } from './types';
-/**
- * Get meta information for a doctype
- * @param doctype - The doctype to get meta information for
- * @param url - The URL to send the request to
- * @returns The meta information for the doctype
- * @public
- */
-declare const methods: {
-    getMeta: (doctype: string, url?: string) => Promise<MetaResponse>;
-};
-export { queries, typeDefs, methods };
-export { StonecropClient } from './client';
-export { buildRecordQuery, buildListQuery } from './query';
-export type { StonecropClientOptions, DoctypeContext } from './client';
-export type { Meta, MetaParser, MetaResponse } from './types';
 export type { DoctypeMeta } from '@stonecrop/schema';
+export { StonecropClient, type StonecropClientOptions, type DoctypeContext } from './client';
+export type { GetRecordResult } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,QAAQ,MAAM,cAAc,CAAA;AACnC,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,SAAS,CAAA;AAkC7D;;;;;;GAMG;AACH,QAAA,MAAM,OAAO;uBACa,MAAM,QAAQ,MAAM,KAAG,OAAO,CAAC,YAAY,CAAC;CAgBrE,CAAA;AAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC1D,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACtE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC7D,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,KAAK,cAAc,EAAE,MAAM,UAAU,CAAA;AAC5F,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA"}

package/dist/src/types/index.d.ts

@@ -1,45 +1,14 @@
 /**
- * @file This file contains all the types that are used in the application.
+ * @file Types for the GraphQL client.
  * @public
  */
+import type { GetRecordResult as SchemaGetRecordResult } from '@stonecrop/schema';
 /**
- * The type of the response from the `getMeta` query.
+ * Result from getRecord - includes the record data and any unknown links requested
  * @public
  */
-export type Meta = {
-    variables: {
-        doctype: string;
-    };
-    response: {
-        getMeta: MetaResponse;
-    };
-};
-/**
- * The type of the response from the `getRecords` query.
- * @public
- */
-export type MetaResponse = {
-    id: string;
-    name: string;
-    workflow: {
-        id: string;
-        name: string;
-        machineId?: string;
-    };
-    schema: {
-        id: string;
-        label: string;
-    }[];
-    actions: {
-        id: string;
-        eventName: string;
-    }[];
-};
-/**
- * The type of the response from the `getMeta` query.
- * @public
- */
-export type MetaParser = {
-    data: Meta['response'];
-};
+export interface GetRecordResult extends SchemaGetRecordResult {
+    /** Link names that were requested but don't exist in the doctype schema */
+    unknownLinks?: string[];
+}
 //# sourceMappingURL=index.d.ts.map

package/dist/src/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG;IAClB,SAAS,EAAE;QACV,OAAO,EAAE,MAAM,CAAA;KACf,CAAA;IAED,QAAQ,EAAE;QACT,OAAO,EAAE,YAAY,CAAA;KACrB,CAAA;CACD,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE;QACT,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,CAAC,EAAE,MAAM,CAAA;KAClB,CAAA;IACD,MAAM,EAAE;QACP,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,EAAE,MAAM,CAAA;KACb,EAAE,CAAA;IACH,OAAO,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,SAAS,EAAE,MAAM,CAAA;KACjB,EAAE,CAAA;CACH,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACxB,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;CACtB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,eAAe,IAAI,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAEjF;;;GAGG;AACH,MAAM,WAAW,eAAgB,SAAQ,qBAAqB;IAC7D,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB"}

package/dist/types/index.js

@@ -1,4 +1,4 @@
 /**
- * @file This file contains all the types that are used in the application.
+ * @file Types for the GraphQL client.
  * @public
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/graphql-client",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -30,12 +30,10 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "decimal.js": "^10.6.0",
     "graphql": "^16.12.0",
-    "graphql-request": "^7.4.0",
     "pluralize": "^8.0.0",
-    "@stonecrop/schema": "0.11.0",
-    "@stonecrop/stonecrop": "0.11.0"
+    "@stonecrop/schema": "0.11.2",
+    "@stonecrop/stonecrop": "0.11.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",

package/src/client.ts

@@ -6,25 +6,10 @@ import type {
 	GetRecordOptions,
 	GetRecordsOptions,
 } from '@stonecrop/schema'
-import { snakeToCamel, toPascalCase } from '@stonecrop/schema'
-import pluralize from 'pluralize'
-
-import { buildRecordQuery } from './query'
+import type { GetRecordResult } from './types'
 
 export type { DoctypeContext, DoctypeRef }
-
-/**
- * Default inflection functions for PostGraphile Amber preset conventions.
- * These match the middleware's default inflection so the client builds
- * queries the server can execute.
- * @internal
- */
-const defaultRecordFieldName = (tableName: string): string => {
-	const singularName = pluralize.singular(tableName)
-	return `${snakeToCamel(singularName)}ById`
-}
-const defaultRecordArgName = (_tableName: string): string => 'id'
-const defaultRecordArgType = (_tableName: string): string => 'UUID!'
+export type { GetRecordResult }
 
 /**
  * Options for creating a Stonecrop client
@@ -35,19 +20,20 @@ export interface StonecropClientOptions {
 	endpoint: string
 	/** Additional HTTP headers to include in requests */
 	headers?: Record<string, string>
-	/** Doctype registry for nested query building */
-	registry?: Map<string, DoctypeMeta>
 }
 
 /**
- * Client for interacting with Stonecrop GraphQL API
+ * Client for interacting with Stonecrop GraphQL API.
+ *
+ * Acts as a transport layer — it passes requests to the middleware and returns
+ * merged results. Does not construct queries itself.
+ *
  * @public
  */
 export class StonecropClient implements DataClient {
 	private endpoint: string
 	private headers: Record<string, string>
 	private metaCache: Map<string, DoctypeMeta> = new Map()
-	private registry?: Map<string, DoctypeMeta>
 
 	constructor(options: StonecropClientOptions) {
 		this.endpoint = options.endpoint
@@ -55,13 +41,14 @@ export class StonecropClient implements DataClient {
 			'Content-Type': 'application/json',
 			...options.headers,
 		}
-		this.registry = options.registry
 	}
 
 	/**
-	 * Execute a GraphQL query
+	 * Execute a GraphQL query against the configured endpoint.
+	 *
 	 * @param query - GraphQL query string
 	 * @param variables - Query variables
+	 * @throws Error if the GraphQL response contains errors
 	 */
 	async query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T> {
 		const response = await fetch(this.endpoint, {
@@ -83,7 +70,8 @@ export class StonecropClient implements DataClient {
 	}
 
 	/**
-	 * Execute a GraphQL mutation
+	 * Execute a GraphQL mutation. Delegates to query() since both use POST.
+	 *
 	 * @param mutation - GraphQL mutation string
 	 * @param variables - Mutation variables
 	 */
@@ -207,65 +195,47 @@ export class StonecropClient implements DataClient {
 	/**
 	 * Get a single record by ID.
 	 *
-	 * When `includeNested` is set, builds a query with sub-selections for descendant
-	 * links and returns ancestor + merged descendants. When omitted, returns flat scalar data.
+	 * Routes through the stonecropRecord resolver which handles nested data
+	 * fetching based on the includeNested option.
 	 *
 	 * @param doctype - Doctype reference (name and optional slug)
 	 * @param recordId - Record ID to fetch
 	 * @param options - Query options (includeNested, maxDepth)
 	 */
-	async getRecord(
-		doctype: DoctypeRef,
-		recordId: string,
-		options?: GetRecordOptions
-	): Promise<Record<string, unknown> | null> {
-		// Nested path: build query with sub-selections
-		if (options?.includeNested) {
-			const meta = await this.getMeta({ doctype: doctype.name })
-			if (!meta) return null
-
-			const query = buildRecordQuery(
-				meta,
-				defaultRecordFieldName,
-				defaultRecordArgName,
-				defaultRecordArgType,
-				this.registry,
-				options
-			)
-
-			const result = await this.query<Record<string, unknown>>(query, { id: recordId })
-
-			const queryName = defaultRecordFieldName(meta.tableName || doctype.name)
-			const record = result[queryName] as Record<string, unknown> | undefined
-
-			if (!record) return null
-
-			if (meta.links && this.registry) {
-				return mergeNestedResults(record, meta, this.registry)
-			}
-
-			return record
-		}
-
-		// Flat path: original query
+	async getRecord(doctype: DoctypeRef, recordId: string, options?: GetRecordOptions): Promise<GetRecordResult> {
 		const result = await this.query<{
-			stonecropRecord: { data: Record<string, unknown> | null }
+			stonecropRecord: { data: Record<string, unknown> | null; unknownLinks?: string[] }
 		}>(
-			`
-			query GetRecord($doctype: String!, $id: String!) {
-				stonecropRecord(doctype: $doctype, id: $id) {
+			`query GetRecord($doctype: String!, $id: String!, $options: JSON) {
+				stonecropRecord(doctype: $doctype, id: $id, options: $options) {
 					data
+					unknownLinks
 				}
+			}`,
+			{
+				doctype: doctype.name,
+				id: recordId,
+				options: options?.includeNested
+					? {
+							includeNested: options.includeNested,
+							maxDepth: options.maxDepth,
+					  }
+					: undefined,
 			}
-			`,
-			{ doctype: doctype.name, id: recordId }
 		)
 
-		return result.stonecropRecord.data
+		return {
+			record: result.stonecropRecord?.data ?? null,
+			unknownLinks: result.stonecropRecord?.unknownLinks,
+		}
 	}
 
 	/**
-	 * Get multiple records with optional filtering and pagination
+	 * Get multiple records with optional filtering and pagination.
+	 *
+	 * Returns flat arrays — the middleware merges connection format (\{ nodes: [...] \})
+	 * into plain arrays before returning.
+	 *
 	 * @param doctype - Doctype reference (name and optional slug)
 	 * @param options - Query options (filters, orderBy, limit, offset)
 	 */
@@ -336,63 +306,12 @@ export class StonecropClient implements DataClient {
 	}
 
 	/**
-	 * Clear the cached doctype metadata
+	 * Clear the cached doctype metadata.
+	 *
+	 * Call this if the server-side doctype schema has changed and you need
+	 * to fetch fresh metadata (e.g., after adding a new field).
 	 */
 	clearMetaCache(): void {
 		this.metaCache.clear()
 	}
 }
-
-/**
- * Merge nested connection results into flat arrays.
- *
- * For `noneOrMany`/`atLeastOne` links, the query returns `{ nodes: [...] }`.
- * This flattens them to just `[]` for easier consumption.
- *
- * For `one`/`atMostOne` links, the result is already flat.
- *
- * @internal
- */
-function mergeNestedResults(
-	record: Record<string, unknown>,
-	meta: DoctypeMeta,
-	registry: Map<string, DoctypeMeta>
-): Record<string, unknown> {
-	if (!meta.links) return record
-
-	const merged = { ...record }
-
-	for (const [fieldname, link] of Object.entries(meta.links)) {
-		const isMany = link.cardinality === 'noneOrMany' || link.cardinality === 'atLeastOne'
-
-		if (isMany) {
-			// Connection result: { nodes: [...] } → flatten to []
-			const targetMeta = registry.get(link.target)
-			if (!targetMeta) continue
-
-			const connectionField = getConnectionFieldFromTarget(targetMeta, meta.tableName || '')
-			const connectionResult = merged[connectionField] as { nodes?: unknown[] } | undefined
-			if (connectionResult?.nodes) {
-				merged[fieldname] = connectionResult.nodes
-				delete merged[connectionField]
-			} else {
-				merged[fieldname] = []
-				delete merged[connectionField]
-			}
-		}
-		// 'one'/'atMostOne' links are already at the right fieldname
-	}
-
-	return merged
-}
-
-/**
- * Derive the connection field name matching the query builder's convention.
- * @internal
- */
-function getConnectionFieldFromTarget(targetMeta: DoctypeMeta, parentTableName: string): string {
-	const targetPlural = pluralize.plural(targetMeta.tableName || '')
-	const targetPascal = toPascalCase(targetPlural)
-	const fkPascal = toPascalCase(parentTableName) + 'Id'
-	return `${targetPascal}By${fkPascal}`
-}

package/src/index.ts

@@ -1,71 +1,4 @@
-import { Decimal } from 'decimal.js'
-import { GraphQLClient } from 'graphql-request'
-
-import { queries } from './queries'
-import typeDefs from './gql/schema'
-import type { Meta, MetaParser, MetaResponse } from './types'
-
-/**
- * Parse the response from the GraphQL server. Converts the stringified JSON to JSON and converts the stringified numbers to Decimal.
- * @param obj - The response from the GraphQL server
- * @returns The parsed response
- * @example
- * const response = '{"data":{"getMeta":{"id":"Issue","name":"Issue","workflow":"{\"machineId\":null,\"name\":\"save\",\"id\":\"1\"}","schema":"[{\"label\":\"Subject\",\"id\":\"1\"}]","actions":"[{\"eventName\":\"save\",\"id\":\"1\"}]"}}}'
- * const parsedResponse = metaParser(response)
- * console.log(parsedResponse)
- * /* Output: {"id": "Issue", "name": "Issue", "workflow": { "machineId": null, "name": "save", "id": "1" }, "schema": [{ "label": "Subject", "id": "1" }], "actions": [{ "eventName": "save", "id": "1" }]}
- */
-const metaParser = (obj: string): MetaParser => {
-	return JSON.parse(obj, (key, value) => {
-		if (typeof value === 'string') {
-			try {
-				return JSON.parse(value, (_key, value) => {
-					if (typeof value === 'string' && !isNaN(Number(value))) {
-						return new Decimal(value)
-					}
-
-					return value
-				})
-			} catch {
-				// if the value is not a stringified JSON, return as it is
-				return value
-			}
-		} else if (!isNaN(Number(value))) {
-			return new Decimal(value as string | number)
-		}
-		return value
-	})
-}
-
-/**
- * Get meta information for a doctype
- * @param doctype - The doctype to get meta information for
- * @param url - The URL to send the request to
- * @returns The meta information for the doctype
- * @public
- */
-const methods = {
-	getMeta: async (doctype: string, url?: string): Promise<MetaResponse> => {
-		const client = new GraphQLClient(url || '/graphql', {
-			fetch: window.fetch,
-			jsonSerializer: {
-				stringify: obj => JSON.stringify(obj), // process the request object before sending; leave as default JSON
-				parse: metaParser, // process the response meta object
-			},
-		})
-
-		const { getMeta } = await client.request<Meta['response'], Meta['variables']>({
-			document: queries.getMeta,
-			variables: { doctype },
-		})
-
-		return getMeta
-	},
-}
-
-export { queries, typeDefs, methods }
-export { StonecropClient } from './client'
-export { buildRecordQuery, buildListQuery } from './query'
-export type { StonecropClientOptions, DoctypeContext } from './client'
-export type { Meta, MetaParser, MetaResponse } from './types'
 export type { DoctypeMeta } from '@stonecrop/schema'
+
+export { StonecropClient, type StonecropClientOptions, type DoctypeContext } from './client'
+export type { GetRecordResult } from './types'

package/src/types/index.ts

@@ -1,48 +1,15 @@
 /**
- * @file This file contains all the types that are used in the application.
+ * @file Types for the GraphQL client.
  * @public
  */
 
-/**
- * The type of the response from the `getMeta` query.
- * @public
- */
-export type Meta = {
-	variables: {
-		doctype: string
-	}
-
-	response: {
-		getMeta: MetaResponse
-	}
-}
-
-/**
- * The type of the response from the `getRecords` query.
- * @public
- */
-export type MetaResponse = {
-	id: string
-	name: string
-	workflow: {
-		id: string
-		name: string
-		machineId?: string
-	}
-	schema: {
-		id: string
-		label: string
-	}[]
-	actions: {
-		id: string
-		eventName: string
-	}[]
-}
+import type { GetRecordResult as SchemaGetRecordResult } from '@stonecrop/schema'
 
 /**
- * The type of the response from the `getMeta` query.
+ * Result from getRecord - includes the record data and any unknown links requested
  * @public
  */
-export type MetaParser = {
-	data: Meta['response']
+export interface GetRecordResult extends SchemaGetRecordResult {
+	/** Link names that were requested but don't exist in the doctype schema */
+	unknownLinks?: string[]
 }