@pidgeon-ai/sdk 1.26.0 → 1.28.0

package/CHANGELOG.md

@@ -7,6 +7,25 @@ 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
+reads, searches, labels, archives, trashes, updates and hands off threads,
+and creates, updates and deletes drafts. Every send, reply, forward, draft
+send, schedule, calendar write and app password answers `403`. `access` on a
+key, `me` and mailbox access can now be `'draft'`. Additive.
+
 ## 1.26.0 — provisioning and teardown by pod
 
 `podsCreate` takes `address` (the same fields as `identitiesCreate`) and `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;
     }>;
@@ -1369,7 +1438,7 @@ type ApiKey = {
     /**
      * The highest rung on any address. Composed with the grant; lower wins.
      */
-    access: 'read' | 'send' | 'admin';
+    access: 'read' | 'draft' | 'send' | 'admin';
     created_by_key_id: string | null;
     last_used_at: string | null;
     revoked_at: string | null;
@@ -1402,7 +1471,7 @@ type ApiKeyCreated = {
     /**
      * The highest rung on any address. Composed with the grant; lower wins.
      */
-    access: 'read' | 'send' | 'admin';
+    access: 'read' | 'draft' | 'send' | 'admin';
     created_by_key_id: string | null;
     last_used_at: string | null;
     revoked_at: string | null;
@@ -1465,7 +1534,7 @@ type Me = {
         /**
          * The highest rung this key reaches on any address. Composed with the grant on the address itself — the lower of the two wins — so this is a ceiling, not a promise.
          */
-        access: 'read' | 'send' | 'admin';
+        access: 'read' | 'draft' | 'send' | 'admin';
         /**
          * True when it reaches every address the workspace owns, including ones created after it. False when it reaches a fixed list.
          */
@@ -1610,7 +1679,10 @@ type MailboxAccess = {
          * For showing a person. A renamed key changes it; never match on it.
          */
         label: string;
-        access: 'read' | 'send' | 'admin';
+        /**
+         * What this principal can do here. A key shows the lower of its ceiling and the grant.
+         */
+        access: 'read' | 'draft' | 'send' | 'admin';
     }>;
     /**
      * Whether this credential may change any of the above.
@@ -1825,7 +1897,7 @@ type PodCreated = {
         /**
          * The highest rung on any address. Composed with the grant; lower wins.
          */
-        access: 'read' | 'send' | 'admin';
+        access: 'read' | 'draft' | 'send' | 'admin';
         created_by_key_id: string | null;
         last_used_at: string | null;
         revoked_at: string | null;
@@ -3105,7 +3177,7 @@ type PodsCreateData = {
          */
         key?: {
             name?: string;
-            access?: 'read' | 'send' | 'admin';
+            access?: 'read' | 'draft' | 'send' | 'admin';
             expires_at?: string | null;
             /**
              * Mint a test-mode key (`pgn_test_`) for the pod instead of a live one.
@@ -5840,7 +5912,7 @@ type KeysCreateData = {
         /**
          * What a key may do. Give an agent the narrowest one that works.
          */
-        access?: 'read' | 'send' | 'admin';
+        access?: 'read' | 'draft' | 'send' | 'admin';
         /**
          * When it stops accepting mail. Expiry suspends; it never deletes, so the correspondence survives.
          */

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;
     }>;
@@ -1369,7 +1438,7 @@ type ApiKey = {
     /**
      * The highest rung on any address. Composed with the grant; lower wins.
      */
-    access: 'read' | 'send' | 'admin';
+    access: 'read' | 'draft' | 'send' | 'admin';
     created_by_key_id: string | null;
     last_used_at: string | null;
     revoked_at: string | null;
@@ -1402,7 +1471,7 @@ type ApiKeyCreated = {
     /**
      * The highest rung on any address. Composed with the grant; lower wins.
      */
-    access: 'read' | 'send' | 'admin';
+    access: 'read' | 'draft' | 'send' | 'admin';
     created_by_key_id: string | null;
     last_used_at: string | null;
     revoked_at: string | null;
@@ -1465,7 +1534,7 @@ type Me = {
         /**
          * The highest rung this key reaches on any address. Composed with the grant on the address itself — the lower of the two wins — so this is a ceiling, not a promise.
          */
-        access: 'read' | 'send' | 'admin';
+        access: 'read' | 'draft' | 'send' | 'admin';
         /**
          * True when it reaches every address the workspace owns, including ones created after it. False when it reaches a fixed list.
          */
@@ -1610,7 +1679,10 @@ type MailboxAccess = {
          * For showing a person. A renamed key changes it; never match on it.
          */
         label: string;
-        access: 'read' | 'send' | 'admin';
+        /**
+         * What this principal can do here. A key shows the lower of its ceiling and the grant.
+         */
+        access: 'read' | 'draft' | 'send' | 'admin';
     }>;
     /**
      * Whether this credential may change any of the above.
@@ -1825,7 +1897,7 @@ type PodCreated = {
         /**
          * The highest rung on any address. Composed with the grant; lower wins.
          */
-        access: 'read' | 'send' | 'admin';
+        access: 'read' | 'draft' | 'send' | 'admin';
         created_by_key_id: string | null;
         last_used_at: string | null;
         revoked_at: string | null;
@@ -3105,7 +3177,7 @@ type PodsCreateData = {
          */
         key?: {
             name?: string;
-            access?: 'read' | 'send' | 'admin';
+            access?: 'read' | 'draft' | 'send' | 'admin';
             expires_at?: string | null;
             /**
              * Mint a test-mode key (`pgn_test_`) for the pod instead of a live one.
@@ -5840,7 +5912,7 @@ type KeysCreateData = {
         /**
          * What a key may do. Give an agent the narrowest one that works.
          */
-        access?: 'read' | 'send' | 'admin';
+        access?: 'read' | 'draft' | 'send' | 'admin';
         /**
          * When it stops accepting mail. Expiry suspends; it never deletes, so the correspondence survives.
          */

package/package.json

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