@domainproof/sdk

Typed Node.js client for the DomainProof public API — claim domains, publish the returned DNS record, and poll for verification, all from server-side code.

Response types are generated from the API's own OpenAPI document (GET /v1/openapi.json); the client itself is hand-written on top of native fetch. No runtime dependencies. Ships both ESM and CommonJS builds, so import and require both work.

Install

npm install @domainproof/sdk

You'll need an API key from a DomainProof project — create one from your dashboard, which mints a dp_test_... and a dp_live_... key together. Test-mode keys only work against .test sandbox domains, which is what the examples below use.

Quickstart

import { DomainProof } from '@domainproof/sdk'

const domainproof = new DomainProof({
  apiKey: process.env.DOMAINPROOF_API_KEY!,
})

const { data, error } = await domainproof.domains.claim({ domain: 'acme.test' })
if (error) throw error

console.log(data.records[0])
// {
//   type: 'TXT',
//   name: '_mysaas-challenge.acme.test',   // "mysaas" is your project's slug
//   value: 'mysaas-verify=8f2a1c4e9b7d3f6a2c5e8b1d4f7a0c3e',
//   purpose: 'ownership',
//   description: 'Proves control of acme.test. This record does nothing else and can be removed after verification.',
//   status: 'pending'
// }

Every method returns { data, error } instead of throwing — check error before using data. error is a DomainProofApiError carrying the API's code (invalid_api_key, not_found, domain_already_claimed, ...) and HTTP status, so you can branch on .code without parsing .message.

By default the client talks to https://api.domainproof.dev. Point it at a local API during development:

const domainproof = new DomainProof({
  apiKey: process.env.DOMAINPROOF_API_KEY!,
  baseUrl: 'http://localhost:3001',
})

Full verify flow

Claim a domain, publish the TXT record it returns, then poll verify until it settles:

import { DomainProof } from '@domainproof/sdk'

const domainproof = new DomainProof({
  apiKey: process.env.DOMAINPROOF_API_KEY!,
})

const claim = await domainproof.domains.claim({
  domain: 'acme.com',
  externalId: 'user_123',
})
if (claim.error) throw claim.error

const [record] = claim.data.records
console.log(
  `Publish a ${record.type} record at ${record.name}:\n${record.value}`,
)

// After publishing the record, poll for it to propagate.
let result = await domainproof.domains.verify(claim.data.id)
while (!result.error && result.data.domain.status === 'pending') {
  await new Promise((resolve) => setTimeout(resolve, 5_000))
  result = await domainproof.domains.verify(claim.data.id)
}

if (result.error) throw result.error
console.log(result.data.domain.status) // 'verified' | 'failed'

Regenerating types

Response types live in src/generated/openapi-types.ts, generated by openapi-typescript from the API's own GET /v1/openapi.json. To regenerate after an API change, run the API locally (pnpm --filter api dev) and then:

pnpm --filter sdk generate

Commit the resulting diff alongside whatever API change prompted it.