TypeScript SDK

The @toolyour/sdk package wraps all ToolYour REST tool routes as TypeScript functions. Use it in Node.js apps, scripts, and CI — or pair it with MCP for agents.

When to use what

Browser-only tools (no API) are not in the SDK — use toolyour.com in the browser.

Single tool with known input? Use the SDK (or REST). Agent with playbooks or a pre-built audit job? Use MCP skills and run_workflow. Same API key and quota on all surfaces.

Install

npm install @toolyour/sdk

Node 18+ (native fetch).

Quick start

import { ToolYour } from "@toolyour/sdk";

const ty = ToolYour({
  apiKey: process.env.TOOLYOUR_API_KEY!, // ty_… from dashboard
});

// SEO — GET-style tools (pass { url })
const meta = await ty.seo.metaTagsAnalyzer({
  url: "https://example.com",
});

// Text — POST JSON
const upper = await ty.text.textCaseConverter({
  text: "hello world",
  case: "uppercase",
});

// Security — GET with url
const headers = await ty.security.securityHeadersAnalyzer({
  url: "https://example.com",
});

// Documents — multipart (Node: Blob or { buffer, name })
import fs from "node:fs";
const pdf = await ty.documents.docxToPdf({
  file: new Blob([fs.readFileSync("report.docx")]),
});
// Returns envelope with result.downloadUrl — same as REST

SDK namespaces

Each OpenAPI tag maps to a namespace on the client:

Full per-tool table: SDK Tool Map (280 tools — purpose, REST path, SDK method, example call, input shape).

How slugs become SDK methods

Slug POST tools (text utilities, calculators, documents, …):

• Public path: /api/v1/text-utilities/text-case-converter
• SDK: ty.text.textCaseConverter({ … })

Rule: hyphen slug → snake operationId → camelCase method (text-case-converter → textCaseConverter).

Explicit routes (most SEO/security/convertors):

• Path: /api/v1/seo-apis/meta-tags-analyzer
• SDK: ty.seo.metaTagsAnalyzer({ url: "…" })

Method name matches OpenAPI operationId (already camelCase).

Generic invoke

When you know the operationId from OpenAPI:

await ty.invoke("gst_calculator", {
  amount: 1000,
  rate: 18,
  mode: "exclusive",
});

await ty.invoke("metaTagsAnalyzer", { url: "https://example.com" });

List all operations in code: ty.listOperations() · namespaces: ty.listNamespaces().

File uploads

Multipart tools accept a file (or module-specific field such as image on convertors):

await ty.convertors.convertToJpg({ image: fileBlob });
await ty.documents.pdfToDocx({ file: fileBlob });

Default response: JSON with result.downloadUrl (presigned, 1 hour). See Calling Tools.

Optional: { delivery: "binary" } as third argument for legacy binary stream (deprecated).

SEO export format

GET SEO tools accept optional markdown/json export via invoke options:

await ty.seo.metaTagsAnalyzer(
  { url: "https://example.com" },
  { format: "markdown" }
);

Same as ?format=markdown on REST.

MCP helpers

Skills and run_workflow are MCP-only (not SDK methods). The SDK ships metadata (MCP_SKILLS, MCP_WORKFLOWS) plus config and a REST shim for individual tools. See SDK vs MCP workflows.

Generate Cursor/Claude config:

import { toolYourMcpServerConfigJson, MCP_WORKFLOWS } from "@toolyour/sdk/mcp";

console.log(
  toolYourMcpServerConfigJson({
    apiKey: process.env.TOOLYOUR_API_KEY!,
  })
);

// List workflow steps to replicate in SDK if needed
console.log(MCP_WORKFLOWS.find((w) => w.id === "full-seo-audit")?.steps);

Call by MCP tool name via REST shim (same quota):

import { invokeMcpTool } from "@toolyour/sdk/mcp";

await invokeMcpTool(
  "metaTagsAnalyzer",
  { url: "https://example.com" },
  { apiKey: process.env.TOOLYOUR_API_KEY! }
);

Local gateway

const ty = ToolYour({
  apiKey: process.env.TOOLYOUR_API_KEY!,
  baseUrl: "http://127.0.0.1:8888",
});

Errors

import { ToolYourQuotaError, ToolYourError } from "@toolyour/sdk";

try {
  await ty.seo.metaTagsAnalyzer({ url: "https://example.com" });
} catch (err) {
  if (err instanceof ToolYourQuotaError) {
    // HTTP 429 — monthly quota exhausted
  }
}

See Errors for REST status codes.

Next steps

• SDK Tool Map — every tool, purpose, example call, REST path
• SDK vs MCP workflows — skills, workflows, when to use each
• Calling Tools — JSON vs multipart, download URLs
• Quickstart — first REST call with curl
• Tool APIs — category guides
• OpenAPI sidebar — request/response schemas