{"id":20879224,"url":"https://github.com/7c/namebright","last_synced_at":"2026-04-21T18:02:27.035Z","repository":{"id":57307616,"uuid":"228436301","full_name":"7c/namebright","owner":"7c","description":"Domain related API Client for NameBright written in Javascript","archived":false,"fork":false,"pushed_at":"2021-01-08T15:22:37.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-20T03:18:48.489Z","etag":null,"topics":["api","domain","javascript","namebright","registrar"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7c.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-16T17:10:18.000Z","updated_at":"2021-01-08T15:22:39.000Z","dependencies_parsed_at":"2022-09-09T19:12:37.285Z","dependency_job_id":null,"html_url":"https://github.com/7c/namebright","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fnamebright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fnamebright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fnamebright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7c%2Fnamebright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7c","download_url":"https://codeload.github.com/7c/namebright/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243258153,"owners_count":20262296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","domain","javascript","namebright","registrar"],"created_at":"2024-11-18T07:15:37.766Z","updated_at":"2025-12-11T18:22:21.752Z","avatar_url":"https://github.com/7c.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NameBright API Client\n\nA TypeScript client for the [NameBright REST API](https://api.namebright.com). This library provides a typed, lightweight wrapper for managing domains, nameservers, renewals, and account details, with automatic token management and debug logging.\n\n- **API Documentation**: [https://api.namebright.com/rest/Help](https://api.namebright.com/rest/Help)\n- **Examples**: [https://github.com/NameBright/DomainApiClientExamples](https://github.com/NameBright/DomainApiClientExamples)\n- **API Access**: Requires authorization from NameBright, configured at [https://legacy.namebright.com/Settings#Api](https://legacy.namebright.com/Settings#Api)\n\n## Features\n\n- **Automatic Token Management**: Handles token fetching and caching.\n- **Typed Interfaces**: Strongly-typed responses for account, domains, nameservers, and renewals.\n- **Debug Logging**: Built-in logging via the `debug` package.\n- **Custom Requests**: Access the underlying Axios instance for flexibility.\n- **Comprehensive API**: Supports domain queries, nameserver updates, renewals, and account summaries.\n- **Lazy Domain Iteration**: Async generator for efficiently iterating over all domains.\n\n## Installation\n\nInstall the package via npm:\n\n```bash\nnpm install --save namebright\n```\n\nRequired dependencies:\n\n- `axios`\n- `query-string`\n- `debug`\n\nInstall them with:\n\n```bash\nnpm install axios query-string debug\n```\n\nFor TypeScript, include type definitions:\n\n```bash\nnpm install @types/debug --save-dev\n```\n\n## IP Restriction\n\nYou may encounter a `400 Usage Violation` error if your IP is not whitelisted. Configure IP whitelisting in your NameBright account at [https://legacy.namebright.com/Settings#Api](https://legacy.namebright.com/Settings#Api). Note: Using `0.0.0.0` to whitelist all IPs is not supported. Find your external IP at [ip8.com](https://ip8.com) and whitelist it.\n\n## Usage\n\n### Initialize the Client\n\nCreate a `NameBright` instance with your authentication credentials:\n\n```typescript\nimport { NameBright, AuthConfig } from 'namebright';\n\nconst auth: AuthConfig = {\n  accountLogin: 'your-account-login',\n  appName: 'your-app-name',\n  appSecret: 'your-app-secret',\n};\n\nconst client = new NameBright(auth);\n```\n\nOverride the default API URL if needed:\n\n```typescript\nconst client = new NameBright(auth, { apiUrl: 'https://custom-api.namebright.com' }, 'namebright3');\n```\n\n### Examples\n\n#### Get Account Balance\n\n```typescript\nconst account = await client.getAccount();\nconsole.log('Account Balance:', account.AccountBalance);\n```\n\n### Account Identifier\nThe `accountIdentifier` method returns the alias used to identify the account. This is useful for debugging and logging and having multiple accounts.\n\n```typescript\nconst accountIdentifier = client.accountIdentifier();\nconsole.log('Account Identifier:', accountIdentifier);\n```\n\n#### List Domains\n\n```typescript\nconst page = await client.getDomains(1, 20);\nconsole.log('Domains:', page.Domains);\nconsole.log('Total Results:', page.ResultsTotal);\n```\n\n#### Iterate Over All Domains\n\nUse the async generator to lazily fetch all domains:\n\n```typescript\nfor await (const domain of client.fetchDomains(20)) {\n  console.log('Domain:', domain.DomainName);\n}\n```\n\n#### Get Domain Details\n\n```typescript\nconst domain = await client.getDomain('example.com');\nconsole.log('Domain Status:', domain.Status);\n```\n\n#### Renew a Domain\n\n```typescript\nconst renewal = await client.renewDomain('example.com', 2);\nconsole.log('Renewal Order ID:', renewal.OrderId);\n```\n\n#### Manage Nameservers\n\n```typescript\nconst nameservers = await client.getNameservers('example.com');\nconsole.log('Nameservers:', nameservers);\n\nconst newNameservers = ['ns1.example.com', 'ns2.example.com'];\nconst applied = await client.setNameservers('example.com', newNameservers);\nconsole.log('Applied Nameservers:', applied);\n```\n\n#### Custom Requests\n\nUse the underlying Axios instance for custom API calls:\n\n```typescript\nconst axiosInstance = client.getClient();\nconst response = await axiosInstance.get('/rest/custom/endpoint');\nconsole.log('Custom Response:', response.data);\n```\n\n## Configuration\n\n### Authentication\n\nRequired credentials:\n\n- `accountLogin`: Your NameBright account login.\n- `appName`: Your registered application name.\n- `appSecret`: Your application secret key.\n\nObtain these from your NameBright account dashboard at [https://legacy.namebright.com/Settings#Api](https://legacy.namebright.com/Settings#Api).\n\n### Options\n\n- `apiUrl`: Override the default API root (`https://api.namebright.com`).\n\n### Debugging\n\nEnable debug logs with the `DEBUG` environment variable:\n\n```bash\nDEBUG=NameBright node your-script.js\n```\n\nThis logs HTTP requests, token fetches, and API responses.\n\n## API Reference\n\n### Methods\n\n- `getAccount(): Promise\u003cNameBrightAccountResponse\u003e`\n  - Fetches the account balance.\n- `getDomains(page?: number, perPage?: number): Promise\u003cNameBrightDomainsPage\u003e`\n  - Lists domains with pagination, returning total results, current page, and domains.\n- `fetchDomains(perPage?: number): AsyncGenerator\u003cNameBrightDomain, void, unknown\u003e`\n  - Lazily iterates over all domains in the account (max `perPage` is 20).\n- `getDomain(domain: string): Promise\u003cNameBrightDomain\u003e`\n  - Retrieves details for a specific domain.\n- `getNameservers(domain: string): Promise\u003cstring[]\u003e`\n  - Gets the nameservers for a domain.\n- `deleteNameservers(domain: string): Promise\u003cvoid\u003e`\n  - Deletes all nameservers for a domain.\n- `deleteNameserver(domain: string, nameserver: string): Promise\u003cvoid\u003e`\n  - Deletes a specific nameserver.\n- `renewDomain(domain: string, years?: number): Promise\u003cNameBrightRenewResponse\u003e`\n  - Renews a domain for 1–10 years.\n- `setNameservers(domain: string, nameservers: string[]): Promise\u003cstring[]\u003e`\n  - Sets nameservers (2–4 required).\n- `getClient(): AxiosInstance`\n  - Returns the Axios instance for custom requests.\n\n### Interfaces\n\n- `AuthConfig`: `{ accountLogin: string, appName: string, appSecret: string }`\n- `NameBrightAccountResponse`: `{ AccountBalance: number }`\n- `NameBrightDomainsPage`: `{ ResultsTotal: number, CurrentPage: number, Domains: NameBrightDomain[] }`\n- `NameBrightDomain`: Domain details (name, status, expiration, etc.).\n- `NameBrightNameserversResponse`: `{ DomainName: string, NameServers: string[] }`\n- `NameBrightRenewResponse`: Renewal order details (order ID, price, etc.).\n\n## Error Handling\n\nThe client throws errors for:\n\n- Missing or invalid authentication credentials.\n- Invalid renewal years (1–10 required).\n- Invalid nameserver count (2–4 required).\n- Token acquisition failures.\n- API request errors (via Axios).\n\nHandle errors with try-catch:\n\n```typescript\ntry {\n  const page = await client.getDomains();\n  console.log(page.Domains);\n} catch (error) {\n  console.error('Error:', error.message);\n}\n```\n\n## Contributing\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/your-feature`).\n3. Commit changes (`git commit -m 'Add your feature'`).\n4. Push to the branch (`git push origin feature/your-feature`).\n5. Open a pull request.\n\n## License\n\nMIT License. See the [LICENSE](LICENSE) file.\n\n## Support\n\nFor issues, open a ticket on the [GitHub repository](https://github.com/7c/namebright) or contact the maintainers.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7c%2Fnamebright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7c%2Fnamebright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7c%2Fnamebright/lists"}