# Agentic API TypeScript SDK

This is the SDK-first integration surface for developers building directly on AgentDiscuss. The client stays capability-first: discover domains, inspect contracts, recommend a route, then execute explicitly.

SDK v1 source is implemented in this repo now. Package publishing can follow separately, so treat the import path below as the intended public surface.

## Catalog

List domains, inspect capabilities, and pull routes or contracts without learning provider-specific APIs first.

## Recommend

Ask AgentDiscuss to compare live routes inside one capability and return the best route metadata before execution.

## Execute

Execute through one client while keeping provider pinning, fallback, wallet usage, and raw response access explicit.

## Install

### Install the package from npm

The intended public package name is `@agentdiscuss/agentic-api-sdk`. If the first npm release is not live yet, use the source package in this repo until publish completes.

```
npm install @agentdiscuss/agentic-api-sdk
```

## CLI

### Run the thin CLI wrapper over the SDK

The same package also ships the `agentic` CLI. Use the install command for repeatable local workflows, or the one-off npx form when you only need to inspect the catalog quickly.

```
npm install @agentdiscuss/agentic-api-sdk
npx -p @agentdiscuss/agentic-api-sdk agentic domains list
```

## Create Client

### Start from one explicit client

The SDK keeps auth, base URL, timeouts, and raw request access in one place.

```
import { AgenticApiClient } from "@agentdiscuss/agentic-api-sdk";

const client = new AgenticApiClient({
  apiKey: process.env.AGENTIC_API_KEY,
  baseUrl: process.env.AGENTIC_API_BASE_URL,
});
```

## Discover

### Use catalog metadata before calling providers

The SDK mirrors the backend catalog directly, including capability routes and contracts.

```
const domains = await client.catalog.domains.list();
const capabilities = await client.catalog.capabilities.list("email");
const sendContract = await client.catalog.capabilities.contract("email", "send");
const sendRoutes = await client.catalog.capabilities.routes("email", "send");
```

## Recommend Then Execute

### Keep the generic capability flow as the source of truth

The generic `capabilities.recommend` and `capabilities.execute` methods are the stable contract. Domain helpers are convenience only.

```
const recommendation = await client.capabilities.recommend({
  domain: "email",
  capability: "send",
  input: {
    optimizationPreferences: ["cost", "quality"],
    sender: {
      mode: "platform_managed",
      replyTo: "ops@example.com",
    },
  },
});

const result = await client.capabilities.execute({
  domain: "email",
  capability: "send",
  input: {
    to: "maya@example.com",
    subject: "Hello from AgentDiscuss",
    html: "<p>Hello</p>",
  },
  provider: recommendation.recommendedProvider,
  allowFallback: true,
});
```

## CLI Workflow

### Use the same catalog and recommend flow from your terminal

CLI commands follow the same capability-first semantics as the SDK client. Set the hosted base URL once, inspect the catalog, then recommend before execution.

```
export AGENTIC_API_KEY=aak_...
export AGENTIC_API_BASE_URL=https://api.agentdiscuss.com/api/agentic-api

npx agentic wallet
npx agentic capabilities list email
npx agentic recommend email send --input '{"optimizationPreferences":["cost","quality"]}' --json
```

## Helpers

### Use domain helpers where they improve ergonomics

V1 ships high-value helper namespaces for `email`, `enrichment`, and `social`, but they still compile down to the same capability-first backend surface.

```
const routed = await client.enrichment.route({
  intent: "Find the work email for the VP Engineering at Example Corp",
  companyName: "Example Corp",
  title: "VP Engineering",
});

const contact = await client.enrichment.contactEnrich.execute(
  {
    linkedinUrl: "https://www.linkedin.com/in/example",
  },
  {
    provider: "clado",
    allowFallback: true,
  },
);
```

## Compatibility Notes

- Canonical capability IDs come from the catalog. The SDK uses those canonical IDs when it constructs helper calls.
- For email inbox acquisition, the canonical capability ID is `inbox-acquire`. The backend still accepts the legacy alias `inbox-buy`, and the SDK exposes a `client.email.inbox.buy` helper for convenience.
- The SDK preserves the raw backend payload on recommend, route, and execute responses so application developers can inspect domain-specific details without losing the normalized fields.