update schema

Author: siisee11

CHANGELOG.md

@@ -1,3 +1,43 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-12-17
+
+### Breaking Changes
+
+- **Renamed class**: `NextrowsClient` → `Nextrows`
+- **Changed constructor signature**: Now accepts an options object instead of positional arguments
+  ```typescript
+  // Before
+  const client = new NextrowsClient("api-key");
+  const client = new NextrowsClient("api-key", { timeout: 60000 });
+
+  // After
+  const client = new Nextrows({ apiKey: "api-key" });
+  const client = new Nextrows({ apiKey: "api-key", timeout: 60000 });
+  ```
+- **Renamed interface**: `NextrowsClientOptions` → `NextrowsOptions`
+
+### Added
+
+- **Zod schema support**: The `extract` method now accepts Zod schemas in addition to JSON Schema objects (requires Zod 3.24+)
+  ```typescript
+  import { z } from "zod/v4";
+
+  const schema = z.array(z.object({
+    name: z.string(),
+    price: z.number()
+  }));
+
+  const result = await client.extract({
+    type: "url",
+    data: ["https://example.com"],
+    schema: schema,
+  });
+  ```
+- Added `JsonSchema` type export for explicit JSON Schema typing
+
+## [0.0.5] and earlier
+
+Initial releases with basic API client functionality.

README.md

@@ -37,9 +37,9 @@ bun add @wordbricks/nextrows-client
 ## Quick Start
 
 ```typescript
-import { NextrowsClient } from "@wordbricks/nextrows-client";
+import { Nextrows } from "@wordbricks/nextrows-client";
 
-const client = new NextrowsClient("sk-nr-your-api-key");
+const client = new Nextrows({ apiKey: "sk-nr-your-api-key" });
 ```
 
 ## API Methods
@@ -60,6 +60,27 @@ if (result.success) {
 }
 ```
 
+#### Using Zod Schema
+
+You can use Zod schemas to define the extraction output structure (requires Zod 3.24+):
+
+```typescript
+import { z } from "zod/v4";
+
+const productSchema = z.array(
+  z.object({
+    name: z.string(),
+    price: z.number(),
+  })
+);
+
+const result = await client.extract({
+  type: "url",
+  data: ["https://example.com/products"],
+  schema: productSchema,
+});
+```
+
 ### Run App
 
 Run a published NextRows app and get JSON output.
@@ -96,7 +117,8 @@ if (result.success && result.data) {
 ## Configuration
 
 ```typescript
-const client = new NextrowsClient("sk-nr-your-api-key", {
+const client = new Nextrows({
+  apiKey: "sk-nr-your-api-key",
   baseUrl: "https://api.nextrows.com", // default
   timeout: 30000, // default, in milliseconds
 });
@@ -107,3 +129,4 @@ const client = new NextrowsClient("sk-nr-your-api-key", {
 - **Fully Typed**: All request and response types are exported for TypeScript support
 - **Simple API**: Easy-to-use methods that mirror the REST API
 - **Configurable**: Custom base URL and timeout options
+- **Zod Support**: Use Zod schemas for type-safe extraction (optional, requires Zod 3.24+)

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@wordbricks/nextrows-client",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/wordbricks/nextrows-client"
@@ -32,7 +32,16 @@
   "dependencies": {
     "axios": "^1.13.2"
   },
+  "peerDependencies": {
+    "zod": "^3.24.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "zod": "^3.25.67",
     "@biomejs/biome": "2.3.8",
     "@types/node": "^25.0.1",
     "concurrently": "9.2.1",

package.json

@@ -1,4 +1,5 @@
 import type { AxiosInstance } from "axios";
+import type { ZodType } from "zod";
 
 /**
  * The type of data source to extract from.
@@ -9,20 +10,18 @@ export type ExtractType = "url" | "text";
 
 /**
  * JSON Schema definition for structured extraction output.
- * Must conform to JSON Schema specification.
+ */
+export interface JsonSchema {
+  [key: string]: unknown;
+}
+
+/**
+ * Schema for structured extraction output.
+ * Can be either a JSON Schema object or a Zod schema.
  *
  * @example
  * ```typescript
- * // Schema for extracting a table as 2D array
- * const schema: ExtractSchema = {
- *   type: "array",
- *   items: {
- *     type: "array",
- *     items: { type: "string" }
- *   }
- * };
- *
- * // Schema for extracting product objects
+ * // Using JSON Schema
  * const schema: ExtractSchema = {
  *   type: "array",
  *   items: {
@@ -33,10 +32,62 @@ export type ExtractType = "url" | "text";
  *     }
  *   }
  * };
+ *
+ * // Using Zod schema (requires Zod 3.24+)
+ * import { z } from "zod/v4";
+ *
+ * const schema = z.array(z.object({
+ *   name: z.string(),
+ *   price: z.number()
+ * }));
  * ```
  */
-export interface ExtractSchema {
-  [key: string]: unknown;
+export type ExtractSchema = JsonSchema | ZodType;
+
+/**
+ * Check if a value is a Zod schema.
+ */
+function isZodSchema(schema: ExtractSchema): schema is ZodType {
+  return (
+    schema !== null &&
+    typeof schema === "object" &&
+    "_def" in schema &&
+    "safeParse" in schema &&
+    typeof (schema as ZodType).safeParse === "function"
+  );
+}
+
+// Cache the zod module to avoid repeated dynamic imports
+let zodModule: { toJSONSchema?: (schema: ZodType) => JsonSchema } | null = null;
+
+/**
+ * Convert a schema to JSON Schema format.
+ * If the schema is a Zod schema, it will be converted using Zod's toJSONSchema().
+ */
+async function convertToJsonSchema(schema: ExtractSchema): Promise<JsonSchema> {
+  if (isZodSchema(schema)) {
+    // Try to use cached zod module first
+    if (zodModule?.toJSONSchema) {
+      return zodModule.toJSONSchema(schema);
+    }
+
+    // Dynamically import zod/v4 (works in both ESM and CJS environments)
+    try {
+      const z = await import("zod/v4");
+      if (z && typeof z.toJSONSchema === "function") {
+        zodModule = z;
+        return z.toJSONSchema(schema) as JsonSchema;
+      }
+    } catch {
+      // import failed, zod/v4 not available
+    }
+
+    throw new Error(
+      "Zod schema conversion requires Zod 3.24+ with zod/v4 subpath. " +
+        "Please install Zod 3.24+ or use a JSON Schema object directly.",
+    );
+  }
+  return schema;
 }
 
 /**
@@ -69,21 +120,30 @@ export interface ExtractRequest {
   prompt?: string;
 
   /**
-   * Optional JSON Schema for consistent and predictable extraction results.
+   * Optional schema for consistent and predictable extraction results.
+   * Can be a JSON Schema object or a Zod schema (requires Zod 3.24+).
    * If not provided, the system will auto-generate the structure based on the data.
    *
    * @example
-   * ```json
-   * {
-   *   "type": "array",
-   *   "items": {
-   *     "type": "object",
-   *     "properties": {
-   *       "name": { "type": "string" },
-   *       "price": { "type": "number" }
+   * ```typescript
+   * // Using JSON Schema
+   * schema: {
+   *   type: "array",
+   *   items: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string" },
+   *       price: { type: "number" }
    *     }
    *   }
    * }
+   *
+   * // Using Zod schema (requires Zod 3.24+)
+   * import { z } from "zod/v4";
+   * schema: z.array(z.object({
+   *   name: z.string(),
+   *   price: z.number()
+   * }))
    * ```
    */
   schema?: ExtractSchema;
@@ -151,6 +211,11 @@ export async function extract(
   client: AxiosInstance,
   request: ExtractRequest,
 ): Promise<ExtractResponse> {
-  const response = await client.post<ExtractResponse>("/v1/extract", request);
+  // Convert Zod schema to JSON Schema if needed
+  const payload = request.schema
+    ? { ...request, schema: await convertToJsonSchema(request.schema) }
+    : request;
+
+  const response = await client.post<ExtractResponse>("/v1/extract", payload);
   return response.data;
 }