@xyz17711/url-extract 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# @xyz17711/url-extract
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Publish](https://github.com/17711-services/clients/actions/workflows/publish-node.yml/badge.svg)](https://github.com/17711-services/clients/actions/workflows/publish-node.yml)
+[![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
+[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).
+
+## Install
+
+```bash
+npm install @xyz17711/url-extract
+```
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `getCompanyProfile` | [Deprecated - use company_profile_get_profile] Company profile from a domain or a name as valid JSON ($0.009, x402) |
+| `getStructuredData` | URL extract with a question: ask any web page a question and get structured data as JSON that matches your schema ($0.02, x402) |
+
+## Quickstart
+
+```typescript
+import { Client } from "@xyz17711/url-extract";
+
+const client = new Client("https://api.17711.xyz/registry/url-extract-service");
+// see the Methods table above for every available call and its request/response type
+```
+
+## Paying past the free quota
+
+Every gated tool allows a small number of free calls per day; beyond that it returns a 402
+challenge. Without a wallet configured, this client throws `PaymentRequiredError` with the price,
+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");
+try {
+  await client.getCompanyProfile(/* ... */);
+} catch (e) {
+  if (e instanceof PaymentRequiredError) {
+    console.log(`needs ${e.priceUsdc} USDC on ${e.network}, payable to ${e.payTo}`);
+  }
+}
+```
+
+To pay automatically, configure a wallet on the client -- the private key should come from your
+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", {
+  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
+  x402MaxTotalSpendUsdc: 1.0,         // refuse once this WALLET's lifetime spend would exceed it
+});
+```
+
+**Never commit a private key.** Both spend caps are required together with the key -- a wallet
+with real funds and no explicit caps refuses to construct at all (`WalletConfigError`), on
+purpose. The cumulative cap is tracked per wallet address, shared by every `Client` you construct
+with that same key in this process.
+
+## LangChain.js
+
+```typescript
+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 tools = new UrlExtractToolkit(client).getTools();
+```
+
+Requires the optional `@langchain/core`+`zod` peer dependencies (`npm install @langchain/core
+zod`) -- importing the base package above never requires them; only `@xyz17711/url-extract/langchain`
+does.
+
+## License
+
+MIT -- see [`LICENSE`](../../LICENSE), shared by every language's client library in the
+`clients` repo this package lives in.

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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 declare class Client extends BaseClient {
+    /** [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) */
+    getStructuredData(request: GetStructuredDataRequest): Promise<GetStructuredDataResponse>;
+}
+export { ClientOptions };

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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(...)`. */
+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) {
+        return this.post("/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) {
+        return this.post("/v1/url-extract/get_structured_data", request);
+    }
+}

package/dist/langchain.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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";
+export declare class UrlExtractToolkit {
+    private client;
+    constructor(client: Client);
+    getTools(): (import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        company_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        domain: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        language: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, {
+        company_name?: string | null | undefined;
+        domain?: string | null | undefined;
+        language?: string | null | undefined;
+    }, {
+        company_name?: string | null | undefined;
+        domain?: string | null | undefined;
+        language?: string | null | undefined;
+    }, import("./index.js").GetCompanyProfileResponse, unknown, "getCompanyProfile"> | import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+        max_age_seconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        question: z.ZodString;
+        schema: z.ZodOptional<z.ZodUnknown>;
+        url: z.ZodString;
+    }, z.core.$strip>, {
+        question: string;
+        url: string;
+        max_age_seconds?: number | null | undefined;
+        schema?: unknown;
+    }, {
+        question: string;
+        url: string;
+        max_age_seconds?: number | null | undefined;
+        schema?: unknown;
+    }, import("./index.js").GetStructuredDataResponse, unknown, "getStructuredData">)[];
+}

package/dist/langchain.js

@@ -0,0 +1,24 @@
+/**
+ * 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";
+export class UrlExtractToolkit {
+    constructor(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/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@xyz17711/url-extract",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "default": "./dist/langchain.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@xyz17711/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=0.3",
+    "zod": "^3 || ^4"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5",
+    "@langchain/core": "^1.2",
+    "zod": "^4"
+  }
+}