@getcolter/sdk

@getcolter/sdk

Official Node.js SDK for Colter.

It supports:

• Hosted API client (/api/v1/*): check, results, shares (revocable share links + PDF).
• Authenticated Lens helpers for traffic, alerts, protocol health, journeys, and portfolio data.
• Local CLI runner wrapper: programmatic access to CLI-only features like verify, replay, diff, export.

Installation

npm install @getcolter/sdk

Quick start

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)

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)

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

// 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.

client.lensTraffic({ siteId, period? }): Promise<LensTrafficResponse>

Fetch Lens traffic analytics. The response includes agent/path/product buckets plus optional by_source and capture metadata that tells you whether the site is using full edge/log capture or partial beacon capture.

Error handling

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
• LensTrafficResponse, LensCaptureProfile, LensSourceBucket, LensTrafficComparison, LensTier

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.