@wishknish/knishio-client-ts 0.9.4 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wishknish/knishio-client-ts",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "productName": "Knish.IO TypeScript SDK Client",
   "description": "TypeScript implementation of the Knish.IO SDK to consume Knish.IO GraphQL APIs with enhanced type safety.",
   "license": "GPL-3.0-or-later",
@@ -67,7 +67,7 @@
     "jssha": "^3.3.1",
     "tslib": "^2.8.1",
     "wonka": "^6.3.5",
-    "zod": "^3.23.8"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/isomorphic-fetch": "^0.0.39",
@@ -113,7 +113,7 @@
     "README.md",
     "LICENSE"
   ],
-  "packageManager": "yarn@4.6.0",
+  "packageManager": "yarn@4.15.0",
   "engines": {
     "node": ">=18.0.0"
   }

package/src/index.ts

@@ -359,7 +359,10 @@ export {
 // VERSION AND SDK INFORMATION
 // =============================================================================
 
-export const SDK_VERSION = '1.0.0'
+// MUST equal package.json's "version". The CI `version consistency` job enforces this via
+// .github/scripts/check-version.sh, which parses this exact line — keep the literal form
+// `export const SDK_VERSION = '<semver>'` intact so the gate can read it.
+export const SDK_VERSION = '0.9.5'
 export const SDK_NAME = 'KnishIO-Client-TS'
 export const COMPATIBLE_SERVER_VERSIONS = [4, 5]
 

package/src/instance/rules/Callback.ts

@@ -69,7 +69,7 @@ const CallbackParamsSchema = z.object({
   action: z.string().min(1, 'Action cannot be empty'),
   metaType: z.union([z.string(), z.null()]).optional(),
   metaId: z.union([z.string(), z.null()]).optional(),
-  meta: z.union([z.instanceof(Meta), z.record(z.unknown()), z.null()]).optional(),
+  meta: z.union([z.instanceof(Meta), z.record(z.string(), z.unknown()), z.null()]).optional(),
   address: z.union([z.string(), z.null()]).optional(),
   token: z.union([z.string(), z.null()]).optional(),
   amount: z.union([z.string(), z.null()]).optional(),

package/src/schemas/index.ts

@@ -62,6 +62,21 @@ import { z } from 'zod'
 const hexStringRegex = /^[0-9a-fA-F]+$/
 const base17HashRegex = /^[0-9a-g]+$/
 
+// Zod 3's `.url()` was `try { new URL(v) } catch` and returned the input UNCHANGED.
+// Zod 4's `z.url()` returns the normalized `URL.href` instead — it strips default ports and
+// lowercases the host — and there is no opt-out. The parsed `uri` is the endpoint the client
+// actually talks to (KnishIOClient destructures it out of the validated config), so a
+// refinement is used here: it validates exactly as v3 did without rewriting the value.
+const urlString = (message = 'Invalid URL') =>
+  z.string().refine((value) => {
+    try {
+      new URL(value)
+      return true
+    } catch {
+      return false
+    }
+  }, message)
+
 export const HexStringSchema = z.string()
   .regex(hexStringRegex, 'Must be a valid hexadecimal string')
   .brand<'HexString'>()
@@ -115,7 +130,7 @@ export const CellSlugSchema = z.string()
 // =============================================================================
 
 export const AtomIsotopeSchema = z.enum(['C', 'V', 'U', 'T', 'M', 'I', 'R', 'B', 'F'], {
-  errorMap: () => ({ message: 'Invalid atom isotope. Must be one of: C, V, U, T, M, I, R, B, F' })
+  error: 'Invalid atom isotope. Must be one of: C, V, U, T, M, I, R, B, F'
 })
 
 // =============================================================================
@@ -135,7 +150,7 @@ export const AtomMetaDataSchema = z.object({
 }).strict()
 
 export const MetaDataSchema: z.ZodType<Record<string, any>> = z.lazy(() =>
-  z.record(z.union([
+  z.record(z.string(), z.union([
     MetaDataValueSchema,
     MetaDataSchema,
     z.array(MetaDataSchema)
@@ -186,7 +201,7 @@ export const MoleculeParamsSchema = z.object({
 // =============================================================================
 
 export const KnishIOClientConfigSchema = z.object({
-  uri: z.union([z.string().url(), z.array(z.string().url())]).optional(),
+  uri: z.union([urlString(), z.array(urlString())]).optional(),
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional(),
   client: z.unknown().optional(),
   socket: z.unknown().optional(),
@@ -209,7 +224,7 @@ export const AuthTokenParamsSchema = z.object({
 export const AuthParamsSchema = z.object({
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional(),
   encrypt: z.boolean().optional(),
-  callback: z.function().args(z.unknown()).returns(z.void()).optional()
+  callback: z.custom<(arg: unknown) => void>((value) => typeof value === 'function').optional()
 }).strict()
 
 export const GuestAuthParamsSchema = z.object({
@@ -224,7 +239,7 @@ export const TransferParamsSchema = z.object({
   recipient: z.union([WalletAddressSchema, z.string()]),
   amount: z.union([z.number().positive(), z.string().min(1)]),
   token: z.union([TokenSlugSchema, z.string()]).optional(),
-  callbackUrl: z.union([z.string().url(), z.null()]).optional(),
+  callbackUrl: z.union([urlString(), z.null()]).optional(),
   metaType: z.union([MetaTypeSchema, z.string(), z.null()]).optional(),
   metaId: z.union([MetaIdSchema, z.string(), z.null()]).optional(),
   meta: z.union([MetaDataSchema, z.null()]).optional()
@@ -278,7 +293,7 @@ export const MetaQueryParamsSchema = z.object({
   value: z.union([z.string(), z.null()]).optional(),
   latest: z.union([z.boolean(), z.null()]).optional(),
   filter: z.union([z.array(MetaFilterSchema), z.null()]).optional(),
-  queryArgs: z.union([z.record(z.unknown()), z.null()]).optional(),
+  queryArgs: z.union([z.record(z.string(), z.unknown()), z.null()]).optional(),
   count: z.union([z.number().int().min(1), z.null()]).optional(),
   countBy: z.union([z.string(), z.null()]).optional(),
   cellSlug: z.union([CellSlugSchema, z.string(), z.null()]).optional()
@@ -316,7 +331,7 @@ export const SignatureResultSchema = z.object({
 
 export const GraphQLRequestSchema = z.object({
   query: z.string().min(1, 'GraphQL query cannot be empty'),
-  variables: z.record(z.unknown()).optional(),
+  variables: z.record(z.string(), z.unknown()).optional(),
   operationName: z.union([z.string(), z.null()]).optional()
 }).strict()
 
@@ -327,13 +342,13 @@ export const GraphQLErrorSchema = z.object({
     column: z.number().int().min(1)
   })).optional(),
   path: z.array(z.union([z.string(), z.number()])).optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 export const GraphQLResponseSchema = z.object({
   data: z.unknown().optional(),
   errors: z.array(GraphQLErrorSchema).nullable().optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 // =============================================================================
@@ -343,8 +358,8 @@ export const GraphQLResponseSchema = z.object({
 export const SubscriptionOptionsSchema = z.object({
   operationName: z.string().optional(),
   query: z.string().optional(),
-  variables: z.record(z.unknown()).optional(),
-  callback: z.function().args(z.unknown()).returns(z.void()).optional()
+  variables: z.record(z.string(), z.unknown()).optional(),
+  callback: z.custom<(arg: unknown) => void>((value) => typeof value === 'function').optional()
 }).strict()
 
 // =============================================================================
@@ -364,7 +379,7 @@ export const ValidationResultSchema = z.object({
 
 export const ErrorContextSchema = z.object({
   operation: z.string().optional(),
-  parameters: z.record(z.unknown()).optional(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
   timestamp: z.number().int().min(0).optional(),
   stack: z.string().optional()
 }).strict()
@@ -407,7 +422,7 @@ export const KnishIOErrorTypeSchema = z.enum([
  * Validates and parses data using a Zod schema with enhanced error messages
  */
 export function parseWithSchema<T>(
-  schema: z.ZodSchema<T>,
+  schema: z.ZodType<T>,
   data: unknown,
   context?: string
 ): T {
@@ -428,7 +443,7 @@ export function parseWithSchema<T>(
  * Type-safe validation that returns a result object instead of throwing
  */
 export function validateWithSchema<T>(
-  schema: z.ZodSchema<T>,
+  schema: z.ZodType<T>,
   data: unknown
 ): { success: true; data: T } | { success: false; error: string } {
   const result = schema.safeParse(data)
@@ -444,7 +459,7 @@ export function validateWithSchema<T>(
  * Validates multiple values with their respective schemas
  */
 export function validateMultiple<T extends Record<string, any>>(
-  validations: { [K in keyof T]: { schema: z.ZodSchema<T[K]>; data: unknown } }
+  validations: { [K in keyof T]: { schema: z.ZodType<T[K]>; data: unknown } }
 ): T {
   const result = {} as T
   

package/src/validation/ValidationService.ts

@@ -182,9 +182,7 @@ export class ValidationService {
         KNISHIO_SERVER_SDK_VERSION: process.env.KNISHIO_SERVER_SDK_VERSION
       }
 
-      // cast: EnvironmentConfig uses .default()/.optional() so its inferred input≠output type and
-      // doesn't structurally match safeParse's ZodType<T> param; ZodTypeAny sidesteps the mismatch.
-      const parseResult = safeParse(Schemas.EnvironmentConfig as z.ZodTypeAny, env)
+      const parseResult = safeParse(Schemas.EnvironmentConfig, env)
       
       if (!parseResult.success) {
         return {

package/src/validation/schemas.ts

@@ -55,6 +55,20 @@ License: https://github.com/WishKnish/KnishIO-Client-TS/blob/master/LICENSE
 
 import { z } from 'zod'
 
+// Zod 3's `.url()` returned the input UNCHANGED; Zod 4's `z.url()` returns the normalized
+// `URL.href` (strips default ports, lowercases the host) with no opt-out. `KnishIOClientConfig
+// .uri` and `KNISHIO_NODE_URI` both flow into the endpoint the client actually calls, so a
+// refinement is used: it validates exactly as v3 did without rewriting the value.
+const urlString = (message = 'Invalid URL') =>
+  z.string().refine((value) => {
+    try {
+      new URL(value)
+      return true
+    } catch {
+      return false
+    }
+  }, message)
+
 // =============================================================================
 // CORE TYPE SCHEMAS (2025 TYPESCRIPT PATTERN)
 // =============================================================================
@@ -92,7 +106,12 @@ export const TokenSlugSchema = createBrandedSchema('TokenSlug',
 )
 
 export const BatchIdSchema = createBrandedSchema('BatchId',
-  z.string().uuid('Invalid batch ID format')
+  // v3's `.uuid()` regex, inlined verbatim. Zod 4's `z.uuid()` additionally enforces the
+  // RFC 9562 version/variant nibbles and would reject batch IDs v3 accepted.
+  z.string().regex(
+    /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/,
+    'Invalid batch ID format'
+  )
 )
 
 export const CellSlugSchema = createBrandedSchema('CellSlug',
@@ -152,7 +171,7 @@ export const AtomMetaDataSchema = z.object({
 export const NormalizedMetaSchema = z.object({
   key: z.string(),
   value: z.union([z.string(), z.number(), z.boolean(), z.null()])
-}).passthrough() // Allow additional properties
+}).loose() // Allow additional properties
 
 // =============================================================================
 // CORE ENTITY SCHEMAS
@@ -199,8 +218,8 @@ export const MoleculeParamsSchema = z.object({
 
 export const KnishIOClientConfigSchema = z.object({
   uri: z.union([
-    z.string().url('Invalid URI format'),
-    z.array(z.string().url('Invalid URI format')).min(1)
+    urlString('Invalid URI format'),
+    z.array(urlString('Invalid URI format')).min(1)
   ]).optional(),
   cellSlug: z.union([CellSlugSchema, z.string()]).optional(),
   client: z.unknown().optional(),
@@ -213,13 +232,18 @@ export const KnishIOClientConfigSchema = z.object({
   defaultRequestPolicy: z.enum(['cache-first', 'cache-only', 'network-only', 'cache-and-network']).nullable().optional()
 }).strict()
 
-// Environment configuration with validation
+// Environment configuration with validation.
+// NOTE: no `.default()` here. The outer `.partial()` wraps every field in `optional()`, so
+// under Zod 3 these defaults never fired (an all-unset env parsed to `{}`). Under Zod 4 they
+// DO fire, and because v4's `.default()` no longer parses the default value they would emit
+// the raw strings 'false' and '4' where the consumer (ValidationService -> KnishIOClientConfig)
+// requires a boolean and a number. Dropping them keeps v3's exact observable output.
 export const EnvironmentConfigSchema = z.object({
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-  KNISHIO_NODE_URI: z.string().url().optional(),
+  NODE_ENV: z.enum(['development', 'production', 'test']).optional(),
+  KNISHIO_NODE_URI: urlString().optional(),
   KNISHIO_CELL_SLUG: z.string().optional(),
-  KNISHIO_LOGGING: z.string().transform(val => val === 'true').default('false'),
-  KNISHIO_SERVER_SDK_VERSION: z.string().transform(val => parseInt(val, 10)).default('4')
+  KNISHIO_LOGGING: z.string().transform(val => val === 'true').optional(),
+  KNISHIO_SERVER_SDK_VERSION: z.string().transform(val => parseInt(val, 10)).optional()
 }).partial()
 
 // =============================================================================
@@ -233,7 +257,7 @@ export const TransferParamsSchema = z.object({
     'Amount must be positive'
   ),
   token: z.union([TokenSlugSchema, z.string()]).optional(),
-  callbackUrl: z.string().url().optional(),
+  callbackUrl: urlString().optional(),
   metaType: z.string().optional(),
   metaId: z.string().optional(),
   meta: MetaDataSchema.optional()
@@ -282,7 +306,7 @@ export const MetaQueryParamsSchema = z.object({
   value: z.string().optional(),
   latest: z.boolean().optional(),
   filter: z.string().optional(),
-  queryArgs: z.record(z.unknown()).optional(),
+  queryArgs: z.record(z.string(), z.unknown()).optional(),
   count: z.number().int().min(0).optional(),
   countBy: z.string().optional(),
   cellSlug: z.union([CellSlugSchema, z.string()]).optional()
@@ -308,7 +332,7 @@ export const AuthTokenParamsSchema = z.object({
 export const AuthParamsSchema = z.object({
   cellSlug: z.union([CellSlugSchema, z.string()]).optional(),
   encrypt: z.boolean().optional(),
-  callback: z.function().optional()
+  callback: z.custom<(...args: unknown[]) => unknown>((value) => typeof value === 'function').optional()
 }).strict()
 
 export const GuestAuthParamsSchema = z.object({
@@ -321,7 +345,7 @@ export const GuestAuthParamsSchema = z.object({
 
 export const GraphQLRequestSchema = z.object({
   query: z.string().min(1),
-  variables: z.record(z.unknown()).optional(),
+  variables: z.record(z.string(), z.unknown()).optional(),
   operationName: z.string().optional()
 }).strict()
 
@@ -332,13 +356,13 @@ export const GraphQLErrorSchema = z.object({
     column: z.number().int()
   })).optional(),
   path: z.array(z.union([z.string(), z.number()])).optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 export const GraphQLResponseSchema = z.object({
   data: z.unknown().optional(),
   errors: z.array(GraphQLErrorSchema).optional(),
-  extensions: z.record(z.unknown()).optional()
+  extensions: z.record(z.string(), z.unknown()).optional()
 }).strict()
 
 // =============================================================================
@@ -357,7 +381,7 @@ export function safeParse<T>(schema: z.ZodType<T>, data: unknown) {
       error: {
         issues: result.error.issues,
         message: result.error.message,
-        formatted: result.error.format()
+        formatted: z.treeifyError(result.error)
       }
     }
   }