npm - domani - Versions diffs - 0.4.12 → 1.0.0 - Mend

domani 0.4.12 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,240 +1,57 @@
 # domani
-Domains and email - for humans and AI agents.
+Official TypeScript SDK for the [domani](https://domani.run) API - domains, email, and identity for AI agents. Fully typed, generated from the OpenAPI spec, zero runtime dependencies (uses the global `fetch`).
-Register domains, manage DNS, create mailboxes, send and receive email. From your terminal, your agent, or the web.
-[![npm version](https://img.shields.io/npm/v/domani.svg)](https://www.npmjs.com/package/domani)
-[![license](https://img.shields.io/npm/l/domani.svg)](https://github.com/gwendall/domani/blob/main/LICENSE)
-## How it works
-domani gives you one account and multiple ways in:
-- **[Web](https://domani.run)** - Dashboard with a full inbox (compose, reply, threads), DNS editor, domain management
-- **CLI** - This package. Everything the web app does, from your terminal
-- **[MCP Server](https://domani.run/mcp)** - 65 tools for Claude Code, Cursor, Windsurf, and any MCP-compatible agent
-- **[OpenClaw](https://openclaw.com)** - `clawhub install domani`
-- **[Agent Skill](https://domani.run/skill.md)** - Step-by-step guide your agent can follow. Install with `npx skills add domani.run`
-- **[REST API](https://domani.run/docs)** - Direct HTTP access to everything
-All interfaces share the same API key and the same data.
+> Looking for the command-line tool? It moved to [`domani-cli`](https://www.npmjs.com/package/domani-cli) (the `domani` command is unchanged: `npm i -g domani-cli`).
 ## Install
 ```bash
-npm install -g domani
+npm install domani
 ```
-Or run directly with `npx`:
+Requires Node 18+ (for global `fetch`), or pass your own `fetch` implementation.
-```bash
-npx domani search myapp .com .dev .ai
-```
+## Quickstart
-## Quick start
+```ts
+import { Domani, DomaniError } from "domani";
-```bash
-# Domain
-domani search myapp .com .io .dev     # Check availability
-domani buy myapp.dev                  # Purchase a domain
-domani connect myapp.dev vercel       # Auto-configure DNS for Vercel
-# Email
-domani email create hello@myapp.dev               # Create hello@myapp.dev
-domani email send hello@myapp.dev \
-  --to hi@friend.com --subject "Hello" --body "Sent from my terminal"
-domani email forward hello@myapp.dev \
-  --forward-to me@gmail.com                        # Forward inbound to personal email
-# Health
-domani status myapp.dev               # DNS, SSL, email, expiry check
-```
+const domani = new Domani({ apiKey: process.env.DOMANI_API_KEY! });
-## Examples
+// Search availability + pricing
+const results = await domani.search({ q: "myagent.com" });
-```bash
-# Find available domains with a budget
-domani search startup --expand --max-price 20
-# AI-powered name suggestions
-domani suggest "minimalist productivity app" --style brandable --tlds com,dev,ai
-# Buy multiple domains at once
-domani buy startup.dev startup.ai --yes
-# Set up Vercel + Google Workspace in two commands
-domani connect startup.dev vercel
-domani connect startup.dev google-workspace
+// Give an agent an inbox
+await domani.createMailboxByAddress({ address: "hi@myagent.com" });
-# Full email workflow: create, send, check inbox, forward
-domani email create hello@startup.dev
-domani email send hello@startup.dev \
-  --to investor@vc.com --subject "Deck" --body "Here's our deck."
-domani email inbox hello@startup.dev --direction in
-domani email forward hello@startup.dev --forward-to me@gmail.com
+// Send mail
+await domani.sendEmailByAddress("hi@myagent.com", {
+  to: "user@example.com",
+  subject: "Hello",
+  text: "Sent from my domani mailbox.",
+});
-# Webhook for inbound emails (for bots, support systems, etc.)
-domani email webhook hello@startup.dev --url https://myapp.dev/hooks/email
-# Export DNS records before making changes
-domani dns startup.dev snapshot
-domani dns startup.dev set TXT @ "v=spf1 include:_spf.google.com ~all"
-# Pipe to jq (auto-JSON when piped, no --json needed)
-domani list | jq '.domains[] | {domain, expires_at}'
-# Introspect command schemas for agent integration
-domani schema buy --json
+// Errors carry the API's structured code + hint
+try {
+  await domani.sendEmailByAddress("hi@myagent.com", { to: "bounced@example.com", text: "..." });
+} catch (e) {
+  if (e instanceof DomaniError) {
+    console.error(e.status, e.code, e.hint); // e.g. 400 RECIPIENTS_SUPPRESSED
+  }
+}
 ```
-## Commands
-### Domains
-```
-domani search <name> [tlds...]    Check availability across TLDs (--expand for 30+)
-domani suggest <prompt>           AI-powered domain suggestions (--style, --lang, --tlds)
-domani buy <domains...>           Purchase one or more domains
-domani transfer <domain>          Transfer from another registrar
-domani renew <domain>             Renew a domain (--years 1-10)
-domani import <domain>            Import a domain you own elsewhere (DNS monitoring only)
-domani list                       List your domains
-domani status <domain>            Health check (DNS, SSL, email, expiry)
-domani tlds                       List all TLDs with pricing (--sort, --max-price)
-domani whois <domain>             WHOIS/RDAP lookup
-```
-### Email
-```
-domani email list                    List all mailboxes
-domani email create user@domain      Create a mailbox
-domani email delete user@domain      Delete a mailbox
-domani email inbox user@domain       List messages (--direction in|out)
-domani email send user@domain        Send an email (--to, --subject, --body, --cc, --bcc)
-domani email forward user@domain     Forward inbound to a personal address (--forward-to)
-domani email webhook user@domain     Forward inbound as JSON to your endpoint (--url)
-domani email setup --domain <domain>       Auto-configure MX, SPF, DKIM, DMARC
-domani email status --domain <domain>      Check email DNS health
-domani email connect --domain <domain> <provider>   Connect external provider (Gmail, Fastmail, Proton)
-```
-### DNS
-```
-domani dns <domain> get            List all DNS records
-domani dns <domain> set <type> <name> <value>   Add/update a record
-domani dns <domain> delete <type> <name>        Remove a record
-domani dns <domain> snapshot       Export DNS to file
-domani dns <domain> restore        Restore DNS from snapshot
-domani nameservers <domain>        Get or set nameservers (--reset for defaults)
-domani connect <domain> <target>   Auto-configure DNS for a provider
-```
-**Supported providers**: Vercel, Netlify, Cloudflare Pages, GitHub Pages, Fly.io, Railway, Render, Google Workspace, Fastmail, Proton Mail.
-### Settings
-```
-domani settings <domain>           View/update auto-renew, WHOIS privacy, security lock
-domani contact [view|set]          Manage WHOIS contact info
-domani parking <domain>            Manage parking page (enable/disable/price)
-domani analytics <domain>          View parking analytics
-domani auth-code <domain>          Get EPP auth code for outbound transfer
-domani transfer-away <domain>      Check outbound transfer status
-```
+## API
-### Account
-```
-domani login                       Log in to domani.run (opens browser)
-domani logout                      Clear saved credentials
-domani me                          Show account info
-domani billing                     Add or update payment method (opens browser)
-domani invoices                    List payment invoices
-domani token                       Print your API key
-domani tokens [list|create|revoke] Manage API tokens (scoped, expiring)
-domani webhooks [action]           Manage webhook endpoints
-```
-### Introspection
-```
-domani schema [command]            Show command schemas for AI agent integration
-domani update                      Update to the latest version
-domani uninstall                   Remove domani CLI and config
-```
-## Agent integration
-Built for AI agents and scripts, not just humans.
-**TTY auto-detect**: When stdout is not a terminal, the CLI automatically switches to JSON output and skips confirmation prompts. No `--json` flag needed.
-```bash
-domani list | jq '.domains[].domain'
-```
-**Structured errors**: In JSON mode, errors include `code`, `hint`, and `fix_command` for auto-recovery:
-```json
-{ "error": "Not logged in", "code": "auth_required", "fix_command": "domani login" }
-```
-| Code | Fix | Description |
-|------|-----|-------------|
-| `auth_required` | `domani login` | Not logged in |
-| `payment_required` | `domani billing` | No payment method on file |
-| `contact_required` | `domani contact set` | WHOIS contact info missing |
-| `validation_error` | Read `hint` | Invalid input |
-| `not_found` | - | Domain doesn't exist or not owned |
-| `rate_limited` | Wait `Retry-After` | Too many requests |
-**Flags**:
-| Flag | Description |
-|------|-------------|
-| `--json` | Force JSON output |
-| `--fields <f>` | Filter JSON fields (comma-separated) |
-| `--dry-run` | Preview mutations without executing |
-| `--yes` | Skip confirmation prompts |
-**Input hardening**: All inputs are validated against path traversal, control characters, query strings, and double encoding - common agent hallucinations.
-**Schema introspection**: Run `domani schema <command> --json` to get parameter types, constraints, and enums before constructing a command.
-## Payments
-Domains are charged to your saved card. Add one at [domani.run/dashboard](https://domani.run/dashboard) or with `domani card add`.
-```bash
-domani buy myapp.dev                     # Charged to saved card
-```
-## Authentication
-| Method | Description |
-|--------|-------------|
-| `domani login` | Interactive login (opens browser) |
-| `$DOMANI_API_KEY` | API key as environment variable |
-| `~/.domani/config.json` | Saved credentials from `domani login` |
-The CLI checks `$DOMANI_API_KEY` first, then falls back to `~/.domani/config.json`.
-```bash
-domani login                             # Interactive (opens browser)
-export DOMANI_API_KEY=domani_sk_...      # Or set env var
-```
+`new Domani({ apiKey, baseUrl?, fetch? })` exposes one typed method per API operation (named after its operationId). Path parameters are positional; request bodies and query objects are typed. Every method returns the parsed JSON response and throws `DomaniError` (`status`, `code`, `hint`, `documentation_url`) on non-2xx.
-Scoped API tokens can be created with `domani tokens create --scopes read,dns --expires-in 86400`.
+Full endpoint reference: <https://domani.run/docs> · OpenAPI spec: <https://domani.run/.well-known/openapi.json>
-## Environment variables
+## Generated
-| Variable | Description |
-|----------|-------------|
-| `DOMANI_API_KEY` | API key (takes precedence over saved config) |
+`src/index.ts` is generated from the domani OpenAPI spec - do not edit it by hand. It is regenerated whenever the API surface changes.
 ## License
-[MIT](LICENSE)
+MIT