@stonecrop/graphql-client 0.8.13 → 0.9.1

package/README.md

@@ -1,2 +1,81 @@
-# Stonecrop GraphQL
+# @stonecrop/graphql-client
 
+Client-side TypeScript interface to the Stonecrop GraphQL API. `StonecropClient` wraps the `stonecrop*` operations added to a PostGraphile schema by `@stonecrop/graphql-middleware`, handling HTTP transport, response unwrapping, and metadata caching so application code works with plain TypeScript objects rather than raw GraphQL.
+
+The client is intentionally thin — it has no knowledge of doctype definitions itself and fetches metadata from the server on demand, caching it in memory for the lifetime of the instance.
+
+While designed to pair with `@stonecrop/graphql-middleware`, the client works against any GraphQL endpoint that implements the `stonecrop*` operation conventions (`stonecropMeta`, `stonecropRecord`, `stonecropRecords`, `stonecropAction`). You can use your own server implementation as long as it conforms to those operation names and the expected response shapes. The `query` and `mutate` methods are also available for interacting with any other operations your schema exposes.
+
+## Installation
+
+```bash
+pnpm add @stonecrop/graphql-client
+```
+
+## Usage
+
+```typescript
+import { StonecropClient } from '@stonecrop/graphql-client'
+
+const client = new StonecropClient({
+  endpoint: 'http://localhost:4000/graphql',
+  headers: { Authorization: `Bearer ${token}` }, // optional
+})
+```
+
+### Metadata
+
+```typescript
+// Fetch DoctypeMeta for a single doctype (cached after first call)
+const meta = await client.getMeta({ doctype: 'SalesOrder' })
+
+// Fetch all registered doctypes
+const allMeta = await client.getAllMeta()
+
+// Bust the in-memory cache
+client.clearMetaCache()
+```
+
+### Reading records
+
+```typescript
+// Single record by ID
+const order = await client.getRecord(meta, 'uuid-here')
+// → Record<string, unknown> | null
+
+// List with optional filtering and pagination
+const orders = await client.getRecords(meta, {
+  filters: { status: 'Draft' },
+  orderBy: 'createdAt',
+  limit: 20,
+  offset: 0,
+})
+// → Record<string, unknown>[]
+```
+
+### Actions
+
+```typescript
+// Dispatch any registered action
+const result = await client.runAction(meta, 'submit', ['uuid-here'])
+// → { success: boolean; data: unknown; error: string | null }
+```
+
+### Raw GraphQL
+
+For queries or mutations not covered by the helpers:
+
+```typescript
+const data = await client.query<{ myTable: unknown[] }>(
+  `query { myTable { id name } }`
+)
+
+const result = await client.mutate<{ createFoo: unknown }>(
+  `mutation CreateFoo($input: CreateFooInput!) { createFoo(input: $input) { foo { id } } }`,
+  { input: { foo: { name: 'bar' } } }
+)
+```
+
+## References
+
+For full method signatures and parameter details, see [API Reference](./api.md).

package/dist/graphql-client.d.ts

@@ -1,217 +1,7 @@
-import { z } from 'zod';
+import { DoctypeMeta } from '@stonecrop/schema';
+import type { RouteContext } from '@stonecrop/schema';
 
-/**
- * Doctype metadata - complete definition of a doctype
- * @public
- */
-export declare const DoctypeMeta: z.ZodObject<{
-    /** Display name of the doctype */
-    name: z.ZodString;
-    /** URL-friendly slug (kebab-case) */
-    slug: z.ZodOptional<z.ZodString>;
-    /** Database table name */
-    tableName: z.ZodOptional<z.ZodString>;
-    /** Field definitions */
-    fields: z.ZodArray<z.ZodObject<{
-        fieldname: z.ZodString;
-        fieldtype: z.ZodEnum<["Data", "Text", "Int", "Float", "Decimal", "Check", "Date", "Time", "Datetime", "Duration", "DateRange", "JSON", "Code", "Link", "Doctype", "Attach", "Currency", "Quantity", "Select"]>;
-        component: z.ZodOptional<z.ZodString>;
-        label: z.ZodOptional<z.ZodString>;
-        width: z.ZodOptional<z.ZodString>;
-        align: z.ZodOptional<z.ZodEnum<["left", "center", "right", "start", "end"]>>;
-        required: z.ZodOptional<z.ZodBoolean>;
-        readOnly: z.ZodOptional<z.ZodBoolean>;
-        edit: z.ZodOptional<z.ZodBoolean>;
-        hidden: z.ZodOptional<z.ZodBoolean>;
-        value: z.ZodOptional<z.ZodUnknown>;
-        default: z.ZodOptional<z.ZodUnknown>;
-        options: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
-        mask: z.ZodOptional<z.ZodString>;
-        validation: z.ZodOptional<z.ZodObject<{
-            errorMessage: z.ZodString;
-        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough">>>;
-    }, "strip", z.ZodTypeAny, {
-        fieldname: string;
-        fieldtype: "Data" | "Text" | "Int" | "Float" | "Decimal" | "Check" | "Date" | "Time" | "Datetime" | "Duration" | "DateRange" | "JSON" | "Code" | "Link" | "Doctype" | "Attach" | "Currency" | "Quantity" | "Select";
-        value?: unknown;
-        options?: string | string[] | Record<string, unknown> | undefined;
-        validation?: z.objectOutputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough"> | undefined;
-        component?: string | undefined;
-        label?: string | undefined;
-        width?: string | undefined;
-        align?: "left" | "center" | "right" | "start" | "end" | undefined;
-        required?: boolean | undefined;
-        readOnly?: boolean | undefined;
-        edit?: boolean | undefined;
-        hidden?: boolean | undefined;
-        default?: unknown;
-        mask?: string | undefined;
-    }, {
-        fieldname: string;
-        fieldtype: "Data" | "Text" | "Int" | "Float" | "Decimal" | "Check" | "Date" | "Time" | "Datetime" | "Duration" | "DateRange" | "JSON" | "Code" | "Link" | "Doctype" | "Attach" | "Currency" | "Quantity" | "Select";
-        value?: unknown;
-        options?: string | string[] | Record<string, unknown> | undefined;
-        validation?: z.objectInputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough"> | undefined;
-        component?: string | undefined;
-        label?: string | undefined;
-        width?: string | undefined;
-        align?: "left" | "center" | "right" | "start" | "end" | undefined;
-        required?: boolean | undefined;
-        readOnly?: boolean | undefined;
-        edit?: boolean | undefined;
-        hidden?: boolean | undefined;
-        default?: unknown;
-        mask?: string | undefined;
-    }>, "many">;
-    /** Workflow configuration */
-    workflow: z.ZodOptional<z.ZodObject<{
-        /** List of workflow states */
-        states: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        /** Actions available in this workflow */
-        actions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-            /** Display label for the action */
-            label: z.ZodString;
-            /** Handler function name or path */
-            handler: z.ZodString;
-            /** Fields that must have values before action can execute */
-            requiredFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            /** Workflow states where this action is available */
-            allowedStates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-            /** Whether to show a confirmation dialog */
-            confirm: z.ZodOptional<z.ZodBoolean>;
-            /** Additional arguments for the action */
-            args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, "strip", z.ZodTypeAny, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }>>>;
-    }, "strip", z.ZodTypeAny, {
-        states?: string[] | undefined;
-        actions?: Record<string, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }> | undefined;
-    }, {
-        states?: string[] | undefined;
-        actions?: Record<string, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }> | undefined;
-    }>>;
-    /** Parent doctype for inheritance */
-    inherits: z.ZodOptional<z.ZodString>;
-    /** Doctype to use for list views */
-    listDoctype: z.ZodOptional<z.ZodString>;
-    /** Parent doctype for child tables */
-    parentDoctype: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    name: string;
-    fields: {
-        fieldname: string;
-        fieldtype: "Data" | "Text" | "Int" | "Float" | "Decimal" | "Check" | "Date" | "Time" | "Datetime" | "Duration" | "DateRange" | "JSON" | "Code" | "Link" | "Doctype" | "Attach" | "Currency" | "Quantity" | "Select";
-        value?: unknown;
-        options?: string | string[] | Record<string, unknown> | undefined;
-        validation?: z.objectOutputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough"> | undefined;
-        component?: string | undefined;
-        label?: string | undefined;
-        width?: string | undefined;
-        align?: "left" | "center" | "right" | "start" | "end" | undefined;
-        required?: boolean | undefined;
-        readOnly?: boolean | undefined;
-        edit?: boolean | undefined;
-        hidden?: boolean | undefined;
-        default?: unknown;
-        mask?: string | undefined;
-    }[];
-    slug?: string | undefined;
-    tableName?: string | undefined;
-    workflow?: {
-        states?: string[] | undefined;
-        actions?: Record<string, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }> | undefined;
-    } | undefined;
-    inherits?: string | undefined;
-    listDoctype?: string | undefined;
-    parentDoctype?: string | undefined;
-}, {
-    name: string;
-    fields: {
-        fieldname: string;
-        fieldtype: "Data" | "Text" | "Int" | "Float" | "Decimal" | "Check" | "Date" | "Time" | "Datetime" | "Duration" | "DateRange" | "JSON" | "Code" | "Link" | "Doctype" | "Attach" | "Currency" | "Quantity" | "Select";
-        value?: unknown;
-        options?: string | string[] | Record<string, unknown> | undefined;
-        validation?: z.objectInputType<{
-            errorMessage: z.ZodString;
-        }, z.ZodTypeAny, "passthrough"> | undefined;
-        component?: string | undefined;
-        label?: string | undefined;
-        width?: string | undefined;
-        align?: "left" | "center" | "right" | "start" | "end" | undefined;
-        required?: boolean | undefined;
-        readOnly?: boolean | undefined;
-        edit?: boolean | undefined;
-        hidden?: boolean | undefined;
-        default?: unknown;
-        mask?: string | undefined;
-    }[];
-    slug?: string | undefined;
-    tableName?: string | undefined;
-    workflow?: {
-        states?: string[] | undefined;
-        actions?: Record<string, {
-            label: string;
-            handler: string;
-            requiredFields?: string[] | undefined;
-            allowedStates?: string[] | undefined;
-            confirm?: boolean | undefined;
-            args?: Record<string, unknown> | undefined;
-        }> | undefined;
-    } | undefined;
-    inherits?: string | undefined;
-    listDoctype?: string | undefined;
-    parentDoctype?: string | undefined;
-}>;
-
-/**
- * Doctype metadata type inferred from Zod schema
- * @public
- */
-export declare type DoctypeMeta = z.infer<typeof DoctypeMeta>;
+export { DoctypeMeta }
 
 /**
  * @file This file contains all the types that are used in the application.
@@ -279,19 +69,7 @@ export declare const queries: {
     getMeta: string;
 };
 
-/**
- * Route context for identifying what doctype/record we're working with.
- * Used by graphql-middleware and graphql-client to resolve schema metadata.
- * @public
- */
-export declare interface RouteContext {
-    /** Doctype name (e.g., 'Task', 'Customer') */
-    doctype: string;
-    /** Optional record ID for viewing/editing a specific record */
-    recordId?: string;
-    /** Additional context properties */
-    [key: string]: unknown;
-}
+export { RouteContext }
 
 /**
  * Client for interacting with Stonecrop GraphQL API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonecrop/graphql-client",
-  "version": "0.8.13",
+  "version": "0.9.1",
   "license": "MIT",
   "type": "module",
   "author": {
@@ -15,30 +15,26 @@
   "bugs": {
     "url": "https://github.com/agritheory/stonecrop/issues"
   },
+  "description": "GraphQL client integration for Stonecrop",
+  "types": "./dist/graphql-client.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/src/index.d.ts",
-        "default": "./dist/graphql-client.js"
-      },
-      "require": "./dist/graphql-client.umd.cjs"
+      "types": "./dist/graphql-client.d.ts",
+      "import": "./dist/graphql-client.js"
     },
-    "./types": {
-      "import": "./dist/src/types/index.d.ts",
-      "require": "./dist/src/types/index.d.ts"
-    }
+    "./types": "./dist/src/types/index.d.ts"
   },
-  "typings": "./dist/src/index.d.ts",
   "files": [
     "dist/*",
     "src/*"
   ],
+  "sideEffects": false,
   "dependencies": {
     "decimal.js": "^10.6.0",
     "graphql": "^16.12.0",
     "graphql-request": "^7.4.0",
-    "@stonecrop/schema": "0.8.13",
-    "@stonecrop/stonecrop": "0.8.13"
+    "@stonecrop/schema": "0.9.1",
+    "@stonecrop/stonecrop": "0.9.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
@@ -68,7 +64,6 @@
   },
   "scripts": {
     "_phase:build": "heft build && vite build && rushx docs",
-    "prepublish": "heft build && vite build && rushx docs",
     "build": "heft build && vite build && rushx docs",
     "dev": "vite",
     "docs": "bash ../common/scripts/run-docs.sh graphql_client",