npm package: @getcolter/sdk
Description: Official Colter SDK for Node.js — check if AI agents can shop your store
Author: Colter
Latest version: 0.3.0

# @getcolter/sdk

Official Node.js SDK for Colter.

It supports:
- Hosted API client (`/api/v1/*`): `check`, `results`, `shares` (revocable share links + PDF).
- Local CLI runner wrapper: programmatic access to CLI-only features like `verify`, `replay`, `diff`, `export`.

## Installation

```bash
npm install @getcolter/sdk
```

## Quick start

```typescript
import { ColterClient } from '@getcolter/sdk';

const client = new ColterClient();

const result = await client.check('example-store.com');

console.log(result.verdict);       // "AGENT-READY" | "PARTIALLY AGENT-READY" | "NOT AGENT-READY"
console.log(result.agent_ready);   // true if any protocol detected
console.log(result.protocols.ucp); // { detected: true, endpoint: "/.well-known/ucp", ... }
console.log(result.protocols.acp); // { detected: false, error: "...", ... }
```

## Share links (revocable + expiring)

```ts
import { ColterClient } from "@getcolter/sdk";

const client = new ColterClient();

const share = await client.createShare({
  result_id: "00000000-0000-0000-0000-000000000000",
  brand: "Acme Agency",
  whitelabel: true,
  client_friendly: true,
  expires_in_days: 30,
});

console.log(share.url); // https://agenticcom.ai/s/<token>
```

## Local CLI runner (feature parity)

```ts
import { ColterCLI } from "@getcolter/sdk";

const cli = new ColterCLI(); // requires `colter` on PATH (or set COLTER_PATH)
const result = await cli.check("example.com");
const { pack } = await cli.verify("example.com", { throwOnFail: false });
```

## Configuration

```typescript
// Custom base URL (for self-hosted or staging)
const client = new ColterClient({
  baseUrl: 'https://staging.agenticcom.ai',
});
```

## API reference

### `new ColterClient(options?)`

Creates a new Colter API client.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseUrl` | `string` | `https://agenticcom.ai` | API base URL |

### `client.check(url): Promise<CheckResult>`

Runs an agent-readiness check against the given store URL. The URL can be a bare domain (e.g. `"example.com"`) or include a scheme.

Throws `ColterError` for HTTP errors (400, 422, 429, 5xx).

### `client.getResult(id): Promise<CheckResult>`

Fetch a stored result by id.

### `client.getResultPdf(id, opts?): Promise<ArrayBuffer>`

Download a PDF for a stored result.

### `client.createShare(req): Promise<ShareCreateResponse>`

Create a revocable share token for a result.

### `client.resolveShare(token): Promise<ShareResolveResponse>`

Resolve a share token to the result plus share metadata.

### `client.getSharePdf(token): Promise<ArrayBuffer>`

Download the branded PDF for a share token.

### `client.revokeShare(token, revokeToken): Promise<{ ok: true; revoked: true }>`

Revoke a share token.

### Error handling

```typescript
import { ColterClient, ColterError } from '@getcolter/sdk';

try {
  const result = await client.check('example.com');
} catch (err) {
  if (err instanceof ColterError) {
    console.error(`Status ${err.statusCode}: ${err.message}`);
    if (err.retryAfter) {
      console.error(`Retry in ${err.retryAfter}s`);
    }
  }
}
```

### Types

All response types are exported:

- `CheckResult` — full readiness check response
- `ProtocolStatus` — UCP, ACP, MCP detection results
- `ProtocolCheck` — single protocol detection
- `WebSignals` — JSON-LD, sitemap, robots.txt, OG tags
- `StoreStatus` — platform, product count, detectability
- `CoverageStatus` — Google and OpenAI ecosystem coverage
- `PlainLanguage` — merchant, agency, developer summaries
- `Verdict` — `"AGENT-READY" | "PARTIALLY AGENT-READY" | "NOT AGENT-READY"`
- `ShareCreateRequest`, `ShareCreateResponse`, `ShareResolveResponse`

## Requirements

- Node.js >= 18.0.0 (uses native `fetch`)
- Zero runtime dependencies

## Rate limits

The Colter API is rate limited to 5 requests per minute per IP. When rate limited, `check()` throws a `ColterError` with `statusCode: 429` and `retryAfter` set to the number of seconds to wait.

## Docs

Full documentation at [agenticcom.ai/docs](https://agenticcom.ai/docs).