@pidgeon-ai/sdk 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ the two would publish a release for every unrelated product deploy.
 Semver applies to **this package's own surface** — the exported names, the
 call shapes, the result shape — not to the API behind it.
 
+## 1.28.0 — DNS hosts for subdomains, and why a record is waiting
+
+Every DNS record (`domainsGet`, `domainsCreate`, `domainsVerify`) gains
+`zone`, `fqdn` and `host_relative`: for `agents.example.com` the DMARC record
+is `_dmarc.agents` in `example.com`, which is what Squarespace, GoDaddy and
+Namecheap ask for. `name` is unchanged. `state` says why `status` is what it
+is — `published` (correct in DNS, waiting on Amazon), `missing`,
+`wrong_value` or `wrong_name` — and `found_at` is where a misplaced record was
+found. For DKIM, `found` is now the CNAME read from DNS rather than Amazon's
+status word. Additive.
+
 ## 1.27.0 — a key that drafts and never sends
 
 `keysCreate` takes `access: 'draft'`, between `read` and `send`: the key

package/dist/index.d.cts

@@ -1282,11 +1282,34 @@ type DomainDetail = {
     dns_records: Array<{
         type: string;
         record_type: string;
+        /**
+         * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+         */
         name: string;
+        /**
+         * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+         */
+        zone: string;
+        /**
+         * The full name, no trailing dot: `_dmarc.agents.example.com`.
+         */
+        fqdn: string;
+        /**
+         * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+         */
+        host_relative: string;
         value: string;
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+        /**
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         */
+        state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
+        /**
+         * Where `found` was read, when that was not `fqdn`.
+         */
+        found_at: string | null;
         description: string;
         checked_at: string | null;
     }>;
@@ -1295,11 +1318,34 @@ type DomainDetail = {
 type DnsRecord = {
     type: string;
     record_type: string;
+    /**
+     * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+     */
     name: string;
+    /**
+     * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+     */
+    zone: string;
+    /**
+     * The full name, no trailing dot: `_dmarc.agents.example.com`.
+     */
+    fqdn: string;
+    /**
+     * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+     */
+    host_relative: string;
     value: string;
     priority: number | null;
     status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+    /**
+     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+     */
+    state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
     found: string | null;
+    /**
+     * Where `found` was read, when that was not `fqdn`.
+     */
+    found_at: string | null;
     description: string;
     checked_at: string | null;
 };
@@ -1310,11 +1356,34 @@ type Verification = {
     dns_records: Array<{
         type: string;
         record_type: string;
+        /**
+         * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+         */
         name: string;
+        /**
+         * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+         */
+        zone: string;
+        /**
+         * The full name, no trailing dot: `_dmarc.agents.example.com`.
+         */
+        fqdn: string;
+        /**
+         * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+         */
+        host_relative: string;
         value: string;
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+        /**
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         */
+        state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
+        /**
+         * Where `found` was read, when that was not `fqdn`.
+         */
+        found_at: string | null;
         description: string;
         checked_at: string | null;
     }>;

package/dist/index.d.ts

@@ -1282,11 +1282,34 @@ type DomainDetail = {
     dns_records: Array<{
         type: string;
         record_type: string;
+        /**
+         * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+         */
         name: string;
+        /**
+         * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+         */
+        zone: string;
+        /**
+         * The full name, no trailing dot: `_dmarc.agents.example.com`.
+         */
+        fqdn: string;
+        /**
+         * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+         */
+        host_relative: string;
         value: string;
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+        /**
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         */
+        state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
+        /**
+         * Where `found` was read, when that was not `fqdn`.
+         */
+        found_at: string | null;
         description: string;
         checked_at: string | null;
     }>;
@@ -1295,11 +1318,34 @@ type DomainDetail = {
 type DnsRecord = {
     type: string;
     record_type: string;
+    /**
+     * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+     */
     name: string;
+    /**
+     * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+     */
+    zone: string;
+    /**
+     * The full name, no trailing dot: `_dmarc.agents.example.com`.
+     */
+    fqdn: string;
+    /**
+     * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+     */
+    host_relative: string;
     value: string;
     priority: number | null;
     status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+    /**
+     * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+     */
+    state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
     found: string | null;
+    /**
+     * Where `found` was read, when that was not `fqdn`.
+     */
+    found_at: string | null;
     description: string;
     checked_at: string | null;
 };
@@ -1310,11 +1356,34 @@ type Verification = {
     dns_records: Array<{
         type: string;
         record_type: string;
+        /**
+         * Relative to the domain: `@` is the domain itself. Kept as it was; see `host_relative`.
+         */
         name: string;
+        /**
+         * The registrable domain the record is published in, from the Public Suffix List: `example.com` for `agents.example.com`.
+         */
+        zone: string;
+        /**
+         * The full name, no trailing dot: `_dmarc.agents.example.com`.
+         */
+        fqdn: string;
+        /**
+         * The name relative to `zone`, which is what most DNS panels ask for: `_dmarc.agents`, or `@` for the zone itself.
+         */
+        host_relative: string;
         value: string;
         priority: number | null;
         status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+        /**
+         * Why `status` is what it is. `published`: correct in public DNS, waiting on the mail provider to confirm (DKIM; usually under an hour). `wrong_name`: our value is at `found_at` instead, often the zone typed twice. Null before the first check.
+         */
+        state: 'connected' | 'published' | 'missing' | 'wrong_value' | 'wrong_name' | 'not_required' | null;
         found: string | null;
+        /**
+         * Where `found` was read, when that was not `fqdn`.
+         */
+        found_at: string | null;
         description: string;
         checked_at: string | null;
     }>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pidgeon-ai/sdk",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Email inboxes for AI agents — TypeScript SDK for Pidgeon: create addresses, send, receive and reply.",
   "keywords": [
     "email",