@xyz17711/url-extract 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@
 [![npm](https://img.shields.io/npm/v/@xyz17711/url-extract)](https://www.npmjs.com/package/@xyz17711/url-extract)
 [![License](https://img.shields.io/npm/l/@xyz17711/url-extract)](https://github.com/17711-services/clients/blob/main/LICENSE)
 
-Typed TypeScript client for **🧩 url-extract-service**, part of the
+Typed TypeScript client for **url-extract-service**, part of the
 [17711.xyz](https://api.17711.xyz) microservice fleet -- pay-per-call APIs settled in USDC via
 [x402](https://x402.org), listed on [x402scan](https://www.x402scan.com/server/f1c7b972-3405-4b75-8b4f-d1bfbd6305ff).
 
@@ -26,10 +26,13 @@ npm install @xyz17711/url-extract
 ```typescript
 import { Client } from "@xyz17711/url-extract";
 
-const client = new Client("https://api.17711.xyz/registry/🧩 url-extract-service");
+const client = new Client(); // talks to https://api.17711.xyz/registry/url-extract-service by default
 // see the Methods table above for every available call and its request/response type
 ```
 
+Pass another base URL (self-hosted instance, test server) as the first argument:
+`new Client("https://my-host.example/registry/url-extract-service")`.
+
 ## Paying past the free quota
 
 Every gated tool allows a small number of free calls per day; beyond that it returns a 402
@@ -39,7 +42,7 @@ network, and payee address attached:
 ```typescript
 import { Client, PaymentRequiredError } from "@xyz17711/url-extract";
 
-const client = new Client("https://api.17711.xyz/registry/🧩 url-extract-service");
+const client = new Client();
 try {
   await client.getCompanyProfile(/* ... */);
 } catch (e) {
@@ -55,7 +58,7 @@ own environment/secrets manager, never a literal string in source code:
 ```typescript
 import { Client } from "@xyz17711/url-extract";
 
-const client = new Client("https://api.17711.xyz/registry/🧩 url-extract-service", {
+const client = new Client({
   x402PrivateKey: process.env.X402_PRIVATE_KEY,
   x402ExpectedNetwork: "eip155:8453", // Base mainnet; use eip155:84532 for Base Sepolia testnet
   x402MaxPaymentUsdc: 0.01,           // refuse any single call above this
@@ -74,7 +77,7 @@ with that same key in this process.
 import { Client } from "@xyz17711/url-extract";
 import { UrlExtractToolkit } from "@xyz17711/url-extract/langchain";
 
-const client = new Client("https://api.17711.xyz/registry/🧩 url-extract-service", { /* ...wallet options... */ });
+const client = new Client({ /* ...wallet options... */ });
 const tools = new UrlExtractToolkit(client).getTools();
 ```
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Typed HTTP client and request/response interfaces for 🧩 url-extract-service.
+ * Typed HTTP client and request/response interfaces for url-extract-service.
  */
 import { Client as BaseClient, type ClientOptions } from "@xyz17711/core";
 export interface DomainInfo {
@@ -94,8 +94,17 @@ export interface GetStructuredDataRequest {
     /** Address of the web page to read (`http` or `https`). */
     url: string;
 }
-/** Typed client for 🧩 url-extract-service, e.g. `client.getCompanyProfile(...)`. */
+/** Production base URL of this service; pass another to self-host or test. */
+export declare const DEFAULT_BASE_URL = "https://api.17711.xyz/registry/url-extract-service";
+/** Typed client for url-extract-service, e.g. `client.getCompanyProfile(...)`. */
 export declare class Client extends BaseClient {
+    /**
+     * `new Client()` talks to the production service. Pass a base URL to target another
+     * instance, and/or wallet options (`new Client({ x402PrivateKey, ... })`) to pay past the
+     * free quota automatically.
+     */
+    constructor(options?: ClientOptions);
+    constructor(baseUrl?: string, options?: ClientOptions);
     /** [Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402) */
     getCompanyProfile(request: GetCompanyProfileRequest): Promise<GetCompanyProfileResponse>;
     /** URL extract with a question: ask any web page a question and get structured data as JSON that matches your schema ($0.02, x402) */

package/dist/index.js

@@ -1,9 +1,17 @@
 /**
- * Typed HTTP client and request/response interfaces for 🧩 url-extract-service.
+ * Typed HTTP client and request/response interfaces for url-extract-service.
  */
 import { Client as BaseClient } from "@xyz17711/core";
-/** Typed client for 🧩 url-extract-service, e.g. `client.getCompanyProfile(...)`. */
+/** Production base URL of this service; pass another to self-host or test. */
+export const DEFAULT_BASE_URL = "https://api.17711.xyz/registry/url-extract-service";
+/** Typed client for url-extract-service, e.g. `client.getCompanyProfile(...)`. */
 export class Client extends BaseClient {
+    constructor(baseUrlOrOptions, options = {}) {
+        const [url, opts] = typeof baseUrlOrOptions === "object"
+            ? [DEFAULT_BASE_URL, baseUrlOrOptions]
+            : [baseUrlOrOptions ?? DEFAULT_BASE_URL, options];
+        super(url, opts);
+    }
     /** [Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402) */
     async getCompanyProfile(request) {
         return this.post("/v1/url-extract/get_company_profile", request);

package/dist/langchain.d.ts

@@ -1,5 +1,5 @@
 /**
- * LangChain.js tools for 🧩 url-extract-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `url-extract/langchain`, never from the package root, so importing the base client never requires them installed.
+ * LangChain.js tools for url-extract-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `url-extract/langchain`, never from the package root, so importing the base client never requires them installed.
  */
 import { z } from "zod";
 import { Client } from "./index.js";

package/dist/langchain.js

@@ -1,5 +1,5 @@
 /**
- * LangChain.js tools for 🧩 url-extract-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `url-extract/langchain`, never from the package root, so importing the base client never requires them installed.
+ * LangChain.js tools for url-extract-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `url-extract/langchain`, never from the package root, so importing the base client never requires them installed.
  */
 import { tool } from "@langchain/core/tools";
 import { z } from "zod";

package/package.json

@@ -1,7 +1,35 @@
 {
   "name": "@xyz17711/url-extract",
-  "version": "0.1.0",
-  "description": "Generated typed client for the 🧩 url-extract-service 17711.xyz microservice.",
+  "version": "0.1.2",
+  "description": "Typed TypeScript client for the 17711.xyz Url Extract API: pay-per-call, settled in USDC via x402.",
+  "license": "MIT",
+  "author": "17711 Services",
+  "homepage": "https://api.17711.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/17711-services/clients.git",
+    "directory": "node/packages/url-extract"
+  },
+  "bugs": {
+    "url": "https://github.com/17711-services/clients/issues"
+  },
+  "keywords": [
+    "x402",
+    "usdc",
+    "api-client",
+    "pay-per-call",
+    "ai-agents",
+    "mcp",
+    "langchain",
+    "url-extract"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -1,117 +0,0 @@
-/**
- * Typed HTTP client and request/response interfaces for 🧩 url-extract-service.
- */
-
-import { Client as BaseClient, type ClientOptions } from "@xyz17711/core";
-
-export interface DomainInfo {
-  /** Years since registration, one decimal. */
-  domain_age_years?: number | null;
-  /** Mail platform deduced from the MX records (`google-workspace`, `microsoft-365`, ...). */
-  email_provider?: string | null;
-  /** Expiration date, `YYYY-MM-DD`. */
-  expires_at?: string | null;
-  /** Sending services declared in the SPF record (`sendgrid`, `mailchimp`, ...). */
-  mail_services: string[];
-  nameservers: string[];
-  /** Registration date, `YYYY-MM-DD`. */
-  registered_at?: string | null;
-  /** The registrable domain the lookups were made for. */
-  registrable_domain: string;
-  /** The registrant, only when it is an organization published in RDAP. */
-  registrant_org?: string | null;
-  registrar?: string | null;
-  /** RDAP status flags (e.g. `client transfer prohibited`), at most 4. */
-  statuses: string[];
-}
-
-export interface GetCompanyProfileResponse {
-  /** Every automatic correction applied to the model's answer. */
-  applied_fixes: unknown[];
-  /** The host that was profiled, lowercased, without scheme or path. */
-  domain: string;
-  /** Public registration and DNS facts about the domain: registrar, registration and expiry dates, age, name servers, public registrant organization, mail platform and sending services. Fields that could not be looked up are absent or empty. */
-  domain_info: DomainInfo;
-  /** Language of the profile's free-text values. */
-  output_language: string;
-  /** The pages that were actually read to build the profile. */
-  pages_read: string[];
-  /** Number of model passes used (2 only when the first answer was incomplete). */
-  passes: number;
-  /** The profile: `name`, `description`, `offering`, `target_customers`, `pricing_summary`, `headquarters`, `founded`, `contact` (`emails`, `phones`) and `social` (`linkedin`, `twitter`, `github`, `facebook`, `instagram`, `youtube`). A value the pages do not state is `null`. */
-  profile: unknown;
-  /** Every schema violation that could not be corrected. */
-  remaining_issues: unknown[];
-  /** `true` when the website was found from `company_name`. */
-  resolved_from_name: boolean;
-  /** Language of the website (ISO 639-1 code). */
-  source_language: string;
-  /** E-mail addresses and social links the model produced that do NOT appear in the pages read; they were removed from `profile` so nothing in it is invented. */
-  unverified_removed: string[];
-  /** Whether the profile satisfies the profile schema after automatic correction. */
-  valid?: boolean | null;
-}
-
-export interface GetCompanyProfileRequest {
-  /** The company's name, when you do not know its website (e.g. `Mistral AI`): the official site is looked up first. `domain` wins when both are given. */
-  company_name?: string | null;
-  /** The company's website: a domain such as `stripe.com` or a full URL (`https://stripe.com/`). Give this or `company_name`. */
-  domain?: string | null;
-  /** Language of the free-text values of the answer (`en` by default; `fr`, `de`, `es`, `pt-BR`...). The pages may be in any language; the JSON keys are always English. */
-  language?: string | null;
-}
-
-export interface GetStructuredDataResponse {
-  /** How old this answer is, in seconds (0 for a fresh read). */
-  age_seconds: number;
-  /** Every automatic correction applied to the model's answer, in order. */
-  applied_fixes: unknown[];
-  /** The structured answer (an object or an array), corrected against `schema` when one was given. */
-  data: unknown;
-  /** The URL actually read, after redirects. */
-  final_url: string;
-  /** `true` when this answer was served from a stored result rather than computed now. */
-  from_cache: boolean;
-  /** `true` when the page text came from a stored copy (fresh enough for `max_age_seconds`). */
-  page_from_cache: boolean;
-  /** `true` when the page was longer than the amount of text the answer is based on. */
-  page_truncated: boolean;
-  /** Every schema violation that could not be corrected. */
-  remaining_issues: unknown[];
-  /** When the page was read to build this answer (UTC). */
-  retrieved_at: string;
-  /** `true` when the page could not be refreshed and an older stored copy was used. */
-  stale_page: boolean;
-  /** The page title, when one could be extracted. */
-  title?: string | null;
-  /** The URL that was requested. */
-  url: string;
-  /** Whether `data` satisfies `schema` after correction; absent when no schema was given. */
-  valid?: boolean | null;
-}
-
-export interface GetStructuredDataRequest {
-  /** The oldest answer you accept, in seconds. Omit it for the default (an identical question about the same page up to 1 hour old); `0` forces a fresh read of the page and a fresh answer. The response always says how old it is. */
-  max_age_seconds?: number | null;
-  /** What to extract or answer, in plain language, e.g. "list the pricing plans with their name and monthly price in USD". */
-  question: string;
-  /** Optional JSON Schema the answer must satisfy. When given, the answer is validated against it and automatically corrected where a safe fix exists (type coercion, missing defaults, out-of-range numbers, unknown properties); anything that cannot be fixed is reported in `remaining_issues`. Omitted = a free-form JSON answer, returned as-is. */
-  schema?: unknown;
-  /** Address of the web page to read (`http` or `https`). */
-  url: string;
-}
-
-/** Typed client for 🧩 url-extract-service, e.g. `client.getCompanyProfile(...)`. */
-export class Client extends BaseClient {
-  /** [Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402) */
-  async getCompanyProfile(request: GetCompanyProfileRequest): Promise<GetCompanyProfileResponse> {
-    return this.post<GetCompanyProfileResponse>("/v1/url-extract/get_company_profile", request);
-  }
-
-  /** URL extract with a question: ask any web page a question and get structured data as JSON that matches your schema ($0.02, x402) */
-  async getStructuredData(request: GetStructuredDataRequest): Promise<GetStructuredDataResponse> {
-    return this.post<GetStructuredDataResponse>("/v1/url-extract/get_structured_data", request);
-  }
-}
-
-export { ClientOptions };

package/src/langchain.ts

@@ -1,36 +0,0 @@
-/**
- * LangChain.js tools for 🧩 url-extract-service, grouped in one Toolkit -- one tool per operation, each just an async function (JS has no separate sync form to generate). Requires the `@langchain/core`+`zod` peer dependencies declared in this package's own package.json -- imported from `url-extract/langchain`, never from the package root, so importing the base client never requires them installed.
- */
-
-import { tool } from "@langchain/core/tools";
-import { z } from "zod";
-import { Client } from "./index.js";
-
-export class UrlExtractToolkit {
-  private client: Client;
-
-  constructor(client: Client) {
-    this.client = client;
-  }
-
-  getTools() {
-    return [
-      tool(
-        async (input) => this.client.getCompanyProfile(input),
-        {
-          name: "getCompanyProfile",
-          description: "[Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402)",
-          schema: z.object({ company_name: z.string().nullable().optional(), domain: z.string().nullable().optional(), language: z.string().nullable().optional() }),
-        },
-      ),
-      tool(
-        async (input) => this.client.getStructuredData(input),
-        {
-          name: "getStructuredData",
-          description: "URL extract with a question: ask any web page a question and get structured data as JSON that matches your schema ($0.02, x402)",
-          schema: z.object({ max_age_seconds: z.number().nullable().optional(), question: z.string(), schema: z.unknown().optional(), url: z.string() }),
-        },
-      ),
-    ];
-  }
-}

package/test/index.test.mjs

@@ -1,41 +0,0 @@
-/**
- * Verifies every url-extract client method sends a request to the expected path/HTTP verb and parses a well-formed response -- one test per operation, real fetch mocked via a plain reassignment of `globalThis.fetch` (no extra test/mocking dependency). Runs against the COMPILED package (`../dist/index.js`) -- build before testing.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { Client } from "../dist/index.js";
-
-test("getCompanyProfile calls the expected path", async () => {
-  const originalFetch = globalThis.fetch;
-  globalThis.fetch = async (url, init = {}) => {
-    const parsed = new URL(url);
-    assert.equal((init.method ?? "GET").toUpperCase(), "POST");
-    assert.equal(parsed.pathname, "/v1/url-extract/get_company_profile");
-    return new Response(JSON.stringify({ applied_fixes: [], domain: "test", domain_info: { domain_age_years: null, email_provider: null, expires_at: null, mail_services: [], nameservers: [], registered_at: null, registrable_domain: "test", registrant_org: null, registrar: null, statuses: [] }, output_language: "test", pages_read: [], passes: 0, profile: null, remaining_issues: [], resolved_from_name: false, source_language: "test", unverified_removed: [], valid: null }), { status: 200 });
-  };
-  try {
-    const client = new Client("https://example.test");
-    const result = await client.getCompanyProfile({ company_name: null, domain: null, language: null });
-    assert.ok(result !== undefined);
-  } finally {
-    globalThis.fetch = originalFetch;
-  }
-});
-
-test("getStructuredData calls the expected path", async () => {
-  const originalFetch = globalThis.fetch;
-  globalThis.fetch = async (url, init = {}) => {
-    const parsed = new URL(url);
-    assert.equal((init.method ?? "GET").toUpperCase(), "POST");
-    assert.equal(parsed.pathname, "/v1/url-extract/get_structured_data");
-    return new Response(JSON.stringify({ age_seconds: 0, applied_fixes: [], data: null, final_url: "test", from_cache: false, page_from_cache: false, page_truncated: false, remaining_issues: [], retrieved_at: "test", stale_page: false, title: null, url: "test", valid: null }), { status: 200 });
-  };
-  try {
-    const client = new Client("https://example.test");
-    const result = await client.getStructuredData({ max_age_seconds: null, question: "test", schema: null, url: "test" });
-    assert.ok(result !== undefined);
-  } finally {
-    globalThis.fetch = originalFetch;
-  }
-});

package/test/langchain.test.mjs

@@ -1,24 +0,0 @@
-/**
- * Verifies every url-extract LangChain tool through the real StructuredTool (`.invoke()`), not just the underlying client method -- catches schema-shape bugs a plain client-method test would miss. Requires the `langchain`/`zod` dev dependencies.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { Client } from "../dist/index.js";
-import { UrlExtractToolkit } from "../dist/langchain.js";
-
-test("getCompanyProfile tool invoke", async () => {
-  globalThis.fetch = async () => new Response(JSON.stringify({ applied_fixes: [], domain: "test", domain_info: { domain_age_years: null, email_provider: null, expires_at: null, mail_services: [], nameservers: [], registered_at: null, registrable_domain: "test", registrant_org: null, registrar: null, statuses: [] }, output_language: "test", pages_read: [], passes: 0, profile: null, remaining_issues: [], resolved_from_name: false, source_language: "test", unverified_removed: [], valid: null }), { status: 200 });
-  const toolkit = new UrlExtractToolkit(new Client("https://example.test"));
-  const t = toolkit.getTools().find((x) => x.name === "getCompanyProfile");
-  const result = await t.invoke({ company_name: "test", domain: "test", language: "test" });
-  assert.ok(result !== undefined);
-});
-
-test("getStructuredData tool invoke", async () => {
-  globalThis.fetch = async () => new Response(JSON.stringify({ age_seconds: 0, applied_fixes: [], data: null, final_url: "test", from_cache: false, page_from_cache: false, page_truncated: false, remaining_issues: [], retrieved_at: "test", stale_page: false, title: null, url: "test", valid: null }), { status: 200 });
-  const toolkit = new UrlExtractToolkit(new Client("https://example.test"));
-  const t = toolkit.getTools().find((x) => x.name === "getStructuredData");
-  const result = await t.invoke({ max_age_seconds: 0, question: "test", schema: null, url: "test" });
-  assert.ok(result !== undefined);
-});

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ES2020",
-    "moduleResolution": "bundler",
-    "declaration": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  },
-  "include": [
-    "src"
-  ]
-}