@hydrafetch/node-sdk 0.1.1 → 0.3.0

package/README.md

@@ -82,6 +82,35 @@ out.results.forEach((item) => console.log(item.url, item.data?.name));
 
 Pass `prompt` instead of, or alongside, `schema` to describe the fields in plain language.
 
+### Zod schemas
+
+If you already use Zod, pass the schema directly. Zod stays optional and is imported only when you
+pass one, so this package still installs with no dependencies of its own.
+
+Zod 4 converts its own schemas and needs nothing else. On Zod 3, install `zod-to-json-schema`
+alongside it and that is used instead. Which one is used is decided by the schema you pass, not by
+what is installed, so a workspace holding both majors still works.
+
+Nested schemas are flattened before sending, including one reused in two places. A schema that
+refers to itself cannot be flattened and is refused rather than sent.
+
+```ts
+import { z } from 'zod';
+
+const Product = z.object({
+  name: z.string().describe("the name of the product this page is selling, not a recommended one"),
+  priceUsd: z.number().describe('its current price in US dollars'),
+});
+
+const out = await hf.extract<z.infer<typeof Product>>(['https://example.com/product/1'], {
+  schema: Product,
+});
+```
+
+`.describe()` is the reason to bother. The description travels with the field to the model doing the
+extraction, and on a page carrying several products, several dates or several addresses it is what
+tells the model which one you meant. The same works in a plain JSON Schema with `description`.
+
 ## Discovery and bulk work
 
 `map` lists a site's URLs for one credit without fetching any page.
@@ -133,6 +162,7 @@ results.forEach((r) => console.log(r.title, r.url, r.data?.markdown));
 await hf.brand('stripe.com');                                 // logos, colours, fonts, socials
 await hf.logo('stripe.com', { theme: 'dark', type: 'icon' }); // one asset
 await hf.styleguide('stripe.com');                            // computed design system
+await hf.styleguide('https://stripe.com/pricing', { maxAge: 0 }); // one page, read fresh
 ```
 
 For logos in a browser use [`@hydrafetch/client-sdk`](https://github.com/Hydrafetch/client-sdk) or [`@hydrafetch/react`](https://github.com/Hydrafetch/react-sdk) with a publishable key. Those bill against logo pulls rather than credits.
@@ -196,7 +226,7 @@ const hf = new Hydrafetch({
 | `extract(urls, options?)` | `ExtractResult<T>` | 5 per URL |
 | `brand(domain)` | `BrandResult` | 5 |
 | `logo(domain, options?)` | `LogoResult` | 1 |
-| `styleguide(domain)` | `StyleguideResult` | 10 |
+| `styleguide(domainOrUrl, options?)` | `StyleguideResult` | 10 |
 | `screenshot(url, options?)` | `ScreenshotResult` | 5 |
 | `images(url)` | `ImagesResult` | 1 |
 | `links(url, options?)` | `ScrapeResult<'links'>` | 1 |

package/dist/index.cjs

@@ -67,6 +67,62 @@ var DEFAULT_MAX_RETRIES = 2;
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function toJsonSchema(schema) {
+  const zodVersion = zodMajorOf(schema);
+  if (zodVersion === null) return schema;
+  const converter = await zodConverter(zodVersion);
+  let converted;
+  try {
+    converted = converter(schema);
+  } catch (cause) {
+    throw new HydrafetchError({
+      code: "SCHEMA_CONVERSION_FAILED",
+      message: `The Zod schema could not be converted: ${cause?.message ?? cause}`,
+      status: 0
+    });
+  }
+  if (JSON.stringify(converted).includes('"$ref":"#')) {
+    throw new HydrafetchError({
+      code: "SCHEMA_CONVERSION_FAILED",
+      message: "The Zod schema refers to itself, so it cannot be expressed as a flat JSON Schema. Flatten the schema or pass JSON Schema directly.",
+      status: 0
+    });
+  }
+  return converted;
+}
+function zodMajorOf(schema) {
+  if (typeof schema !== "object" || schema === null) return null;
+  if (typeof schema.parse !== "function") return null;
+  if ("_zod" in schema) return 4;
+  return "_def" in schema ? 3 : null;
+}
+async function zodConverter(version) {
+  if (version === 4) {
+    const zod = await optionalImport(
+      "zod"
+    );
+    if (zod && typeof zod.toJSONSchema === "function") return zod.toJSONSchema;
+  }
+  const legacy = await optionalImport("zod-to-json-schema");
+  if (legacy && typeof legacy.zodToJsonSchema === "function") {
+    return (schema) => legacy.zodToJsonSchema(schema, { $refStrategy: "none" });
+  }
+  throw new HydrafetchError({
+    code: "SCHEMA_CONVERSION_FAILED",
+    message: `A Zod ${version} schema was passed but nothing here can convert it. Use zod 4, which converts its own schemas, or install zod-to-json-schema alongside zod 3, or pass a JSON Schema.`,
+    status: 0
+  });
+}
+async function optionalImport(name) {
+  try {
+    return await import(
+      /* @vite-ignore */
+      name
+    );
+  } catch {
+    return null;
+  }
+}
 var Hydrafetch = class {
   apiKey;
   baseUrl;
@@ -171,10 +227,12 @@ var Hydrafetch = class {
   search(query, options = {}) {
     return this.request("POST", "/v1/web/search", { query, ...options });
   }
-  extract(urls, options = {}) {
+  async extract(urls, options = {}) {
+    const { schema, ...rest } = options;
     return this.request("POST", "/v1/web/extract", {
       urls: Array.isArray(urls) ? urls : [urls],
-      ...options
+      ...rest,
+      ...schema === void 0 ? {} : { schema: await toJsonSchema(schema) }
     });
   }
   brand(domain) {
@@ -183,8 +241,12 @@ var Hydrafetch = class {
   logo(domain, options = {}) {
     return this.request("GET", "/v1/web/brand/logo", void 0, { domain, ...options });
   }
-  styleguide(domain) {
-    return this.request("GET", "/v1/web/styleguide", void 0, { domain });
+  styleguide(domainOrUrl, options = {}) {
+    const target = /^https?:\/\//i.test(domainOrUrl) ? { url: domainOrUrl } : { domain: domainOrUrl };
+    return this.request("GET", "/v1/web/styleguide", void 0, {
+      ...target,
+      ...options
+    });
   }
   screenshot(url, options = {}) {
     return this.request("POST", "/v1/web/screenshot", { url, ...options });

package/dist/index.d.cts

@@ -90,8 +90,23 @@ interface SearchResult {
     status?: string;
     results: SearchResultItem[];
 }
+/**
+ * A standards-compliant JSON Schema, or a Zod schema you already have.
+ *
+ * Zod is not a dependency of this package and never will be: it is loaded only if you actually
+ * pass one. The reason to pass one is `.describe()`. A field description reaches the model that
+ * does the extraction, and on a page carrying several products or several dates it is what tells
+ * the model which one you meant.
+ */
+type ExtractSchema = Record<string, unknown> | ZodLike;
+/** Structurally a Zod schema, without importing Zod to say so. */
+interface ZodLike {
+    _zod?: unknown;
+    _def?: unknown;
+    parse?: (value: unknown) => unknown;
+}
 interface ExtractOptions {
-    schema?: Record<string, unknown>;
+    schema?: ExtractSchema;
     prompt?: string;
     preferStructure?: boolean;
     enableWebSearch?: boolean;
@@ -170,8 +185,12 @@ interface LogoResult {
     type?: string;
     [key: string]: unknown;
 }
+interface StyleguideOptions {
+    maxAge?: number;
+}
 interface StyleguideResult {
     domain?: string;
+    page?: string;
     colors?: Record<string, unknown>;
     typography?: Record<string, unknown>;
     [key: string]: unknown;
@@ -235,7 +254,7 @@ declare class Hydrafetch {
     extract<T = unknown>(urls: string | string[], options?: ExtractOptions): Promise<ExtractResult<T>>;
     brand(domain: string): Promise<BrandResult>;
     logo(domain: string, options?: BrandOptions): Promise<LogoResult>;
-    styleguide(domain: string): Promise<StyleguideResult>;
+    styleguide(domainOrUrl: string, options?: StyleguideOptions): Promise<StyleguideResult>;
     screenshot(url: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
     images(url: string, options?: {
         maxAge?: number;
@@ -271,4 +290,4 @@ declare class HydrafetchTimeoutError extends HydrafetchError {
     constructor(message: string);
 }
 
-export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideResult, type Usage, type WaitOptions };
+export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type ExtractSchema, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideOptions, type StyleguideResult, type Usage, type WaitOptions, type ZodLike };

package/dist/index.d.ts

@@ -90,8 +90,23 @@ interface SearchResult {
     status?: string;
     results: SearchResultItem[];
 }
+/**
+ * A standards-compliant JSON Schema, or a Zod schema you already have.
+ *
+ * Zod is not a dependency of this package and never will be: it is loaded only if you actually
+ * pass one. The reason to pass one is `.describe()`. A field description reaches the model that
+ * does the extraction, and on a page carrying several products or several dates it is what tells
+ * the model which one you meant.
+ */
+type ExtractSchema = Record<string, unknown> | ZodLike;
+/** Structurally a Zod schema, without importing Zod to say so. */
+interface ZodLike {
+    _zod?: unknown;
+    _def?: unknown;
+    parse?: (value: unknown) => unknown;
+}
 interface ExtractOptions {
-    schema?: Record<string, unknown>;
+    schema?: ExtractSchema;
     prompt?: string;
     preferStructure?: boolean;
     enableWebSearch?: boolean;
@@ -170,8 +185,12 @@ interface LogoResult {
     type?: string;
     [key: string]: unknown;
 }
+interface StyleguideOptions {
+    maxAge?: number;
+}
 interface StyleguideResult {
     domain?: string;
+    page?: string;
     colors?: Record<string, unknown>;
     typography?: Record<string, unknown>;
     [key: string]: unknown;
@@ -235,7 +254,7 @@ declare class Hydrafetch {
     extract<T = unknown>(urls: string | string[], options?: ExtractOptions): Promise<ExtractResult<T>>;
     brand(domain: string): Promise<BrandResult>;
     logo(domain: string, options?: BrandOptions): Promise<LogoResult>;
-    styleguide(domain: string): Promise<StyleguideResult>;
+    styleguide(domainOrUrl: string, options?: StyleguideOptions): Promise<StyleguideResult>;
     screenshot(url: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
     images(url: string, options?: {
         maxAge?: number;
@@ -271,4 +290,4 @@ declare class HydrafetchTimeoutError extends HydrafetchError {
     constructor(message: string);
 }
 
-export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideResult, type Usage, type WaitOptions };
+export { type BatchOptions, type BrandOptions, type BrandResult, type CrawlOptions, type ExtractItem, type ExtractOptions, type ExtractResult, type ExtractSchema, type Format, Hydrafetch, HydrafetchError, type HydrafetchOptions, HydrafetchTimeoutError, type ImagesResult, type JobPage, type JobResult, type JobStatus, type LogoResult, type MapOptions, type MapResult, type PageImage, type PageMetadata, type ScrapeBase, type ScrapeContent, type ScrapeOptions, type ScrapeResult, type ScreenshotOptions, type ScreenshotResult, type SearchOptions, type SearchResult, type SearchResultItem, type StyleguideOptions, type StyleguideResult, type Usage, type WaitOptions, type ZodLike };

package/dist/index.js

@@ -39,6 +39,62 @@ var DEFAULT_MAX_RETRIES = 2;
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function toJsonSchema(schema) {
+  const zodVersion = zodMajorOf(schema);
+  if (zodVersion === null) return schema;
+  const converter = await zodConverter(zodVersion);
+  let converted;
+  try {
+    converted = converter(schema);
+  } catch (cause) {
+    throw new HydrafetchError({
+      code: "SCHEMA_CONVERSION_FAILED",
+      message: `The Zod schema could not be converted: ${cause?.message ?? cause}`,
+      status: 0
+    });
+  }
+  if (JSON.stringify(converted).includes('"$ref":"#')) {
+    throw new HydrafetchError({
+      code: "SCHEMA_CONVERSION_FAILED",
+      message: "The Zod schema refers to itself, so it cannot be expressed as a flat JSON Schema. Flatten the schema or pass JSON Schema directly.",
+      status: 0
+    });
+  }
+  return converted;
+}
+function zodMajorOf(schema) {
+  if (typeof schema !== "object" || schema === null) return null;
+  if (typeof schema.parse !== "function") return null;
+  if ("_zod" in schema) return 4;
+  return "_def" in schema ? 3 : null;
+}
+async function zodConverter(version) {
+  if (version === 4) {
+    const zod = await optionalImport(
+      "zod"
+    );
+    if (zod && typeof zod.toJSONSchema === "function") return zod.toJSONSchema;
+  }
+  const legacy = await optionalImport("zod-to-json-schema");
+  if (legacy && typeof legacy.zodToJsonSchema === "function") {
+    return (schema) => legacy.zodToJsonSchema(schema, { $refStrategy: "none" });
+  }
+  throw new HydrafetchError({
+    code: "SCHEMA_CONVERSION_FAILED",
+    message: `A Zod ${version} schema was passed but nothing here can convert it. Use zod 4, which converts its own schemas, or install zod-to-json-schema alongside zod 3, or pass a JSON Schema.`,
+    status: 0
+  });
+}
+async function optionalImport(name) {
+  try {
+    return await import(
+      /* @vite-ignore */
+      name
+    );
+  } catch {
+    return null;
+  }
+}
 var Hydrafetch = class {
   apiKey;
   baseUrl;
@@ -143,10 +199,12 @@ var Hydrafetch = class {
   search(query, options = {}) {
     return this.request("POST", "/v1/web/search", { query, ...options });
   }
-  extract(urls, options = {}) {
+  async extract(urls, options = {}) {
+    const { schema, ...rest } = options;
     return this.request("POST", "/v1/web/extract", {
       urls: Array.isArray(urls) ? urls : [urls],
-      ...options
+      ...rest,
+      ...schema === void 0 ? {} : { schema: await toJsonSchema(schema) }
     });
   }
   brand(domain) {
@@ -155,8 +213,12 @@ var Hydrafetch = class {
   logo(domain, options = {}) {
     return this.request("GET", "/v1/web/brand/logo", void 0, { domain, ...options });
   }
-  styleguide(domain) {
-    return this.request("GET", "/v1/web/styleguide", void 0, { domain });
+  styleguide(domainOrUrl, options = {}) {
+    const target = /^https?:\/\//i.test(domainOrUrl) ? { url: domainOrUrl } : { domain: domainOrUrl };
+    return this.request("GET", "/v1/web/styleguide", void 0, {
+      ...target,
+      ...options
+    });
   }
   screenshot(url, options = {}) {
     return this.request("POST", "/v1/web/screenshot", { url, ...options });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydrafetch/node-sdk",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Official Node/TypeScript client for the Hydrafetch web data API. Turn any URL into clean Markdown and structured data.",
   "keywords": [
     "hydrafetch",
@@ -47,9 +47,22 @@
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zod": "^4.5.4"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "zod": ">=3",
+    "zod-to-json-schema": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    },
+    "zod-to-json-schema": {
+      "optional": true
+    }
   }
 }