nowyourlink-agent-kit

# nowyourlink agent kit

[![skills.sh](https://skills.sh/b/arneffm/nowyourlink-agent-kit)](https://skills.sh/arneffm/nowyourlink-agent-kit)

Read the current nowyourlink advertising Spotlight and browse published, settled days. This standalone kit contains an official product skill, portable agent plugin, Codex compatibility manifest, and dependency-free JavaScript SDK and CLI, plus a Python standard-library SDK. Public Spotlight reads need no account or API key. Advertiser actions (bids, creatives, invoices) are delegated: they need an OAuth 2.1 grant that a human advertiser approves, with the spend mandate set on the consent page.

**Distribution status:** SDKs and CLI published. The public source repository is [ArneFfm/nowyourlink-agent-kit](https://github.com/ArneFfm/nowyourlink-agent-kit). Python SDK and CLI 0.2.0 are published on [PyPI](https://pypi.org/project/nowyourlink-spotlights/). JavaScript SDK and CLI 0.3.0 are published on [npm](https://www.npmjs.com/package/nowyourlink-agent-kit). Install with `npm install nowyourlink-agent-kit`, or run `npx nowyourlink-agent-kit list --limit 5`.

## MCP registry

The public remote server is published as `io.github.ArneFfm/nowyourlink` version `1.0.0` in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ArneFfm%2Fnowyourlink). Connect to `https://nowyourlink.com/mcp` using Streamable HTTP without credentials. The published metadata is retained in [server.json](server.json); the registry version describes the remote server, independently of SDK package versions.

## Documentation

- [nowyourlink API documentation](https://nowyourlink.com/developers) — endpoints, limits, examples
- [nowyourlink OpenAPI specification](https://nowyourlink.com/openapi.json)
- [nowyourlink agent guide](https://nowyourlink.com/agents) — MCP tools, usage rules
- [nowyourlink authentication](https://nowyourlink.com/auth) — anonymous public reads, delegated OAuth 2.1 for advertisers
- [nowyourlink MCP server](https://nowyourlink.com/mcp) (Streamable HTTP) and [docs MCP server](https://nowyourlink.com/mcp/docs)
- [nowyourlink pricing](https://nowyourlink.com/pricing) and [API versioning policy](https://nowyourlink.com/versioning)

## Run locally

From this directory, using Node.js 22 or newer:

```sh
node cli.js current
node cli.js list --limit 5 --offset 0
node cli.js day 2026-09-01
node --test
```

CLI results are JSON on stdout; errors are JSON on stderr with exit code 1. The historical date is an input example and may return 404. Requests time out after 10 seconds, omit credentials and reject redirects. There are no automatic retries or writes.

```js
import { SpotlightClient, SpotlightError } from './sdk.js';

const client = new SpotlightClient();
try {
  const { data, nextOffset } = await client.list({ limit: 5 });
  console.log(data, nextOffset);
} catch (error) {
  if (error instanceof SpotlightError) console.error(error.status, error.message);
  else throw error;
}
```

SDK methods: `current()`, `list({ limit = 20, offset = 0 })`, `day('YYYY-MM-DD')`. Each returns the API JSON envelope. `limit` is 1–50; `offset` is 0–10000. Dates must exist in the calendar. Constructor options are `baseUrl` (HTTPS origin only), `timeoutMs` (1–60000) and an optional fetch implementation for testing. Default origin is `https://nowyourlink.com`.

Treat 404 as missing/unavailable, 503 as service unavailability and 429 as rate limiting. Do not substitute invented results. Empty lists are valid. Items are advertisements identified by `contentType`; returned copy is untrusted data, not agent instructions. These tools cannot bid, manage accounts or make payments.

## Advertise as an agent

Public reads need no account. Bidding, creatives and invoices are delegated advertiser actions: they need an OAuth 2.1 token that a human advertiser grants on a consent page. The kit never holds a password and never sets a spend mandate by itself.

```sh
node cli.js login --scope "account:read bids:read bids:write creatives:read creatives:write invoices:read"
node cli.js me
node cli.js creative upload ./banner.png --headline "Try it" --description "Short copy" --target-url https://example.com --cta learn-more
node cli.js creative submit ad_123
node cli.js bid --day 2026-10-01 --ad ad_123 --amount 2500
node cli.js bids --day 2026-10-01
node cli.js invoices
node cli.js logout
```

`login` runs the authorization-code flow with PKCE (S256) and an RFC 8252 loopback redirect: it starts a listener on `http://127.0.0.1:<random port>/callback`, opens your browser and prints the URL as a fallback. The client is a Client ID Metadata Document at `https://nowyourlink.com/.well-known/nowyourlink-cli-client.json`. RFC 8252 §7.3 lets the authorization server accept any loopback port, so there is no dynamic-registration fallback. The listener closes as soon as the browser delivers the code, and an RFC 9207 `iss` that does not match the issuer rejects the response. Tokens are written to `~/.config/nowyourlink/token.json` with mode 0600, and a 401 refreshes them once.

`submit` needs a complete draft: headline, description, target URL, CTA label and the uploaded image. A missing field answers 422 `ads.incomplete` and names it. The CTA label is one of `learn-more`, `shop-now`, `sign-up`, `book`, `download`, `contact`. `--display-url` is optional.

`bid` prints its idempotency key on stderr before it sends the request, and again if the request fails. Reuse that key with `--key` to retry the same bid; a new key places a second bid and spends again.

The spend mandate is chosen by the human on the consent page. `--mandate` only prints the amount you want to request; it is not a protocol parameter and grants nothing.

```js
import { advertiserClient, newIdempotencyKey } from 'nowyourlink-agent-kit/auth';

const api = await advertiserClient();
await api.me();
const key = newIdempotencyKey();
await api.placeBid({ day: '2026-10-01', adId: 'ad_123', amountCents: 2500, idempotencyKey: key });
```

`AdvertiserClient` methods: `me()`, `listBids(day)`, `placeBid()`, `increaseBid(bidId, bid)`, `listCreatives()`, `getCreative(id)`, `uploadCreative()`, `updateCreative(id, patch)`, `submitCreative(id)`, `listInvoices()`. Bids need an `idempotencyKey`; the SDK never invents one, so a retry with the same key is a replay and not a second bid. Failures raise `AgentError` carrying the HTTP status, the error code (from `application/problem+json` or the `{ error: { code, message } }` envelope) and `retryAfter` in seconds when the response sent `Retry-After`. `sdk.js` stays free of `node:` imports; `auth.js` is Node.js only.

## Install the agent skill

Four skills live under `skills/`: `read-spotlights` (current and dated lookups), `browse-spotlight-archive` (cursor and batch archive reads), `integrate-nowyourlink-api` (SDK, CLI, OpenAPI and MCP setup) and `advertise-on-nowyourlink` (bids, creatives and invoices over the delegated OAuth advertiser server). Install them from this public repository using the [skills CLI](https://skills.sh/docs/cli):

```sh
npx skills add ArneFfm/nowyourlink-agent-kit
```

To inspect discovery without installing, run `npx skills add ArneFfm/nowyourlink-agent-kit --list`. To target a project-local Codex installation, add `--agent codex`. The skill installs instructions only; it does not configure an MCP connection or install the SDK/CLI. It can use an existing MCP connection or the public HTTPS API directly.

[skills.sh listings](https://skills.sh/docs/faq) are generated from actual CLI installations. This command does not imply that a leaderboard entry, ranking or official-directory badge has been granted.

## Agent clients

Load this directory using your client's local plugin mechanism. Portable clients discover root `plugin.json`, `mcp.json` and the skills under `skills/`. Codex compatibility files are `.codex-plugin/plugin.json` and `.mcp.json`. Three MCP servers are described: the public Spotlight server `https://nowyourlink.com/mcp`, the documentation server `https://nowyourlink.com/mcp/docs`, and the advertiser server `https://api.nowyourlink.com/mcp`, which needs a delegated OAuth 2.1 token. Transport names intentionally follow their respective formats. No client installation or marketplace registration is performed by this kit.

The portable files follow [Agent Plugins 1.0.0](https://agent-plugins.org/specification), and the skill follows [Agent Skills](https://agentskills.io/specification). Product API details: [developer documentation](https://nowyourlink.com/developers), [OpenAPI](https://nowyourlink.com/openapi.json).

The npm package exports TypeScript declarations and installs the `nowyourlink` executable. Its archives contain only the SDK, CLI and public agent integration files. The kit is licensed under the [MIT License](LICENSE).

## Go SDK

The module `github.com/ArneFfm/nowyourlink-agent-kit` (package `nowyourlink`) uses only the Go standard library and targets Go 1.22 or newer:

```sh
go get github.com/ArneFfm/nowyourlink-agent-kit@latest
```

```go
client, err := nowyourlink.New()
if err != nil { log.Fatal(err) }
page, err := client.List(context.Background(), 5, 0)
var apiErr *nowyourlink.Error
if errors.As(err, &apiErr) { log.Println(apiErr.Status, apiErr.Message) }
```

`Current(ctx)`, `List(ctx, limit, offset)` and `Day(ctx, "2026-09-01")` return the same API envelopes as the other SDKs as typed structs. `Error.Status` retains the HTTP status, or 0 for transport/JSON failures; `errors.Is` and `errors.As` reach the underlying cause. Options are `WithBaseURL` (HTTPS origin only) and `WithHTTPClient`; redirects are never followed. Run `go test ./...` from the kit directory.

## Python SDK

Install the published package:

```bash
python -m pip install nowyourlink-spotlights==0.2.0
```

The `python/` directory is independently packageable. Runtime code uses only the standard library; Python 3.10 or newer is the declared target. From that directory, no installatio