@datarails-ai/dr-cli 0.0.1-locked → 1.6.71

package/dist/skills/dr-cli/reference/desk.md

@@ -0,0 +1,472 @@
+# Desk
+
+`dr desk` fronts the Desk service. Most of it is outbound-email onboarding
+(`/api/desk/v1/teams/...`) so the integrations team can set up a customer's
+outbound email themselves; `ticket create` (`/api/desk/v1/tickets/`) opens a
+ticket without the web UI. Before the onboarding commands
+existed the documented procedure required an encryption script and a hand-written
+`INSERT INTO smtp_connections`, which that team cannot run: no Key Vault access,
+no database access, and the email gateway that holds the credentials has no
+public ingress at all.
+
+Desk is the edge-facing orchestrator in front of that gateway. It holds the
+service-to-service token, so nothing here needs cluster access.
+
+## The two paths are not interchangeable
+
+|                 | SendGrid domain auth                     | SMTP app password                                     |
+| --------------- | ---------------------------------------- | ----------------------------------------------------- |
+| Scope           | per organization                         | per (org, team)                                       |
+| Customer secret | none                                     | the app password                                      |
+| Customer's work | 3 CNAMEs + 1 DMARC TXT                   | MFA, app password, forward rule, approve verification |
+| Completion      | asynchronous - DNS, then a 15-min poller | synchronous - a real SMTP handshake                   |
+| Re-runnable     | yes, idempotent                          | `set` only onto a soft-deleted row; an ACTIVE row 409s - use `smtp rotate`, which replaces the credential in place and never deactivates the row |
+
+**The gateway picks SMTP ahead of SendGrid at send time and never reads
+`sendgrid_domains` when choosing a sender.** So an SMTP connection silently
+overrides a verified SendGrid domain for that team. Moving a customer from an app
+password onto SendGrid means _removing the SMTP connection_, not just verifying
+the domain - verifying alone changes nothing. `register` and `verify` both emit a
+warning when an active SMTP connection exists; do not ignore it.
+
+## Auth - read this first
+
+Every **onboarding** verb is admin-only, and "admin" means `SUPER_ADMIN` or
+`ADMIN` on the target org's Django profile. (`ticket create` is the one
+exception - see its own section.) Two consequences:
+
+1. **There is no `org_id` argument anywhere.** The org comes from the token, so
+   it is decided entirely by `--server` and `--account`. Check with
+   `dr whoami --server <s> --account <a>` before a write.
+2. **An integrations engineer is not an admin in a customer org**, so the normal
+   identity is an impersonation:
+
+```
+dr login-as <customer-admin-email> --server US
+dr desk teams list --server US --account <customer-admin-email>
+```
+
+The impersonation JWT carries the _target's_ `role` claim, which is what Desk
+maps, so this works where your own operator identity would 403.
+
+Note `SUPPORT_SUPER_ADMIN` and `DR_CONNECT_ADMIN` are **not** admin as far as
+Desk is concerned - only `SUPER_ADMIN` and `ADMIN` are. A support identity that
+works elsewhere in the CLI can still 403 here.
+
+## SMTP app-password path
+
+```
+dr desk teams list --server US --account <admin>
+dr desk smtp set ap@acme.com --password-file ./pw --server US --account <admin>
+```
+
+- `<team>` takes a **team id, a support email, or a team name** - whichever the
+  operator has in front of them. `teams list` returns all three, so nothing has
+  to be transcribed. Matching is exact and case-insensitive, email checked
+  first; it is deliberately not a substring match, because "AP" quietly
+  selecting "AP - EMEA" would write a customer credential to the wrong team. An
+  ambiguous or unknown **name or support email** lists the candidates and
+  refuses rather than guessing. A numeric id is passed straight through without
+  a lookup - it is unambiguous by construction, so the server is the authority
+  on whether it exists, and an id that does not resolve fails on the write.
+- Resolution happens before the confirm token is minted, so the token binds the
+  numeric id. If a name starts resolving to a different team between the plan
+  and the redeem, the token stops working instead of writing to a new target.
+
+- The password comes from `--password-file` or `--password-stdin`, **never** as
+  an argument. A credential in `argv` lands in shell history and in `ps` output
+  on a shared host. A single trailing newline is stripped; interior spaces are
+  kept, because providers display app passwords in groups of four and the server
+  normalises exactly that shape.
+- `--smtp-username` defaults to the team's `support_email`. `--smtp-host` is
+  inferred for Gmail and O365 only; any other domain **must** pass it, because
+  Google Workspace on a custom domain is indistinguishable from any other host
+  by the address alone and a wrong host gives a confusing timeout instead of an
+  error.
+- A team with no `support_email` shows as `(none set)` in `teams list` and cannot
+  be onboarded on this path yet - the username has nothing to default to.
+- **`verified: false` on a 200 is the common outcome, not a bug.** The credential
+  is stored and the provider rejected it: usually MFA is off on the mailbox, or
+  an account password was supplied instead of an app password. Both are
+  customer-side fixes, which is why the row is deliberately kept rather than
+  rolled back - re-run after they fix it.
+- Two-step confirm (Tier A: word-gated on prod). It chooses the team's outbound
+  sender, and this CLI has no delete verb, so there is no one-command inverse.
+- **On prod, use `--password-file`, not `--password-stdin`, on Linux.** Tier A
+  means the confirm step wants a human, and on Linux that human is prompted on
+  the TTY - but `--password-stdin` has already consumed stdin to EOF by then.
+  The command **refuses this combination up front**, naming the flag and
+  pointing at `--password-file`, rather than draining the pipe and failing in
+  the gate with "must be confirmed by a person" or a bogus "word did not match".
+  The refusal applies on the plan phase as well as the redeem - the machine's
+  channel situation is the same either way - but only on production tenants and
+  only where no desktop dialog exists; macOS and Windows prompts are dialogs
+  that never touch stdin. Separately, `--password-stdin` with a TERMINAL on
+  stdin (a pasted command with no pipe attached) is refused everywhere: typing
+  the credential there would echo it to the screen and into scrollback.
+- **Delete the password file when you are done.** The plan/confirm split means it
+  has to survive the token window, so it cannot be a process substitution - which
+  leaves a customer credential in plaintext in your working directory:
+
+```
+dr desk smtp set 6 --password-file ./pw --server US --account <admin>
+# ... redeem the token ...
+rm ./pw
+```
+
+### Replacing a credential that is already stored
+
+`set` refuses a team that already has an ACTIVE connection. `rotate` is the
+in-place replacement - same password sources, same `--smtp-username` /
+`--smtp-host` / `--smtp-port` flags, same two-step confirm gate:
+
+```
+dr desk smtp rotate 6 --password-file ./pw --server US --account <admin>
+# ... redeem the token ...
+rm ./pw
+```
+
+- The row is **never deactivated**, so the team keeps sending authenticated
+  throughout. Deactivating it first - the old recovery - drops outbound to
+  unauthenticated SendGrid until the new credential lands.
+- Omitted flags keep what is **stored**, not what the support email would infer,
+  so a custom-domain Workspace team does not need `--smtp-host` again.
+- It **404s when there is nothing to rotate** rather than creating a connection,
+  so a mistyped team is an error and not a silent onboarding.
+- Tier A: the previous password is encrypted and not versioned, so there is no
+  way back to it.
+
+## Troubleshooting an existing connection
+
+```
+dr desk smtp get ap@acme.com  --server US --account <admin>
+dr desk smtp test ap@acme.com --server US --account <admin>
+```
+
+- `get` touches no mail provider, so it is safe to run while diagnosing. It
+  never returns the password.
+- **`active: NO` means the row exists but does not route.** The gateway's read
+  returns soft-deleted rows while send-time selection skips them, so "there is a
+  connection" and "that connection sends the mail" are different questions. This
+  is the answer to "we deleted the SMTP connection but mail still goes over
+  SMTP" - check the org-wide row too.
+- Both `get` and `test` are **team-scoped with no org-wide fallback**, while
+  send time _does_ fall back. So "no connection for this team" does not mean the
+  team has no SMTP sender - an org-wide row may be sending for it. Both messages
+  say so.
+- `test` re-runs the real handshake **without re-submitting the password**. Use
+  it after the customer enables MFA on the existing password - the stored value
+  becomes valid without changing.
+- A **regenerated** app password is a new value, so `test` cannot help: it
+  re-handshakes the stale stored one and fails, and no 409 appears on that path
+  to redirect you. Use `smtp rotate` to replace it in place.
+- A rejection prints the provider's own error plus a likely cause, and prints
+  **no** cause when the error maps to nothing known - a wrong diagnosis sends
+  the operator back to the customer for the wrong thing.
+
+## Register the team's inbound address - the two-stage funnel dance
+
+The address the team carries changes TWICE during onboarding, and the order is
+the whole trick. The provider's forwarding-verification email is sent **to the
+region funnel address itself** - the customer's mailbox appears nowhere in its
+recipient headers - so that one email can only become a ticket while the team's
+configured address IS the funnel address.
+
+**Stage 1 - before the customer creates their forwarding rule**, put the
+region's funnel address on the team:
+
+```
+# <team> is the team NAME or numeric id - NOT the address being set.
+# <REGION> and the address must name the SAME region - see below.
+dr desk support-email set "AP" <REGION funnel address> --server <REGION> --account <admin>
+```
+
+Each region has its own inbound funnel address. The live list is **not
+reproduced here** — this reference ships inside the published npm package, and
+the funnel addresses are real inbound mailboxes. Get the address for the region
+you are onboarding from the internal Desk runbook, or from the desk owners,
+before running the command above. Passing the wrong region's address silently
+routes the customer's mail to another environment's funnel.
+
+Sibling environments have no address of their own: **DEV-1 shares DEV's** and
+**TEST-1 through TEST-7 share TEST's** (they inherit the family configuration).
+A shared funnel is physically one mail route, so inbound onboarding on a
+sibling environment lands wherever that shared funnel is pointed - check with
+R&D before running the funnel dance on a sibling environment.
+
+The customer now creates their auto-forward rule to that same funnel address;
+the provider's verification email arrives **as a ticket on this team** in the
+Desk UI. Approve the forwarding with the link/code from that ticket.
+
+**Stage 2 - immediately after approving**, switch the team to the customer's
+real mailbox:
+
+```
+dr desk support-email set "AP" ap@acme.com --server US --account <admin>
+```
+
+**Do not run `smtp set` between the stages.** Its username default follows the
+team's address *at execute time*, so during the window it would store the
+customer's credential under the funnel address - a sender no provider will
+accept. Save the app password only after stage 2, or pass `--smtp-username`
+explicitly.
+
+Do not linger between the stages: the funnel address is a **unique registry
+key**, so while it sits on this team, every inbound funnel email routes here. Forwarded customer mail keeps the customer's mailbox in its
+original `To:` header, which is what routes it after stage 2 - the funnel
+address is only ever needed to catch the one verification email. Stage 2
+releases the key by deregistering the funnel address (observed live, not
+inferred: the deregister fires on every address change).
+
+**Only one onboarding per funnel address can run at a time - and siblings share
+one** (DEV with DEV-1, TEST with TEST-1..7), so coordinate across the whole
+family, not just your own environment. A second stage 1 while another team
+holds the funnel address does NOT fail loudly - the
+CLI reports success (the field write works), but the registry registration
+collides in a background task, so the verification ticket lands on the OTHER
+team (or, same-org, silently steals the funnel from it). If the verification
+ticket does not appear on your team within a few minutes: on an environment
+still awaiting the DR-52424 release, the release is the cause, not a collision;
+otherwise assume a collision or a failed registration and escalate to R&D, who
+can inspect and release the registry row. The CLI prints this same warning on
+every stage-1 plan and success output, keyed on the funnel domain.
+
+> **DR-52424 (inbound registration 401) - fixed, rollout-gated.** Before
+> 2026-08-25, the monolith minted its gateway token without an org claim, so
+> the registry write this command dispatches 401'd everywhere and inbound mail
+> was silently dropped. The fix (dr-datarails-server #7358) is merged and
+> verified end-to-end on DEV. On any environment that has not yet received a
+> monolith release containing it, the old behaviour still applies - confirm a
+> test email becomes a ticket before telling a customer inbound is live.
+
+Two-step confirm, Tier A: a wrong address routes the customer's mail to another
+team or nowhere, and this CLI has no deregister verb. The confirm token is bound
+to the team **and** the address, so a token cannot be redeemed against a
+different address than the one the plan step showed.
+
+## SendGrid domain-auth path
+
+```
+dr desk sendgrid register acme.com --server US --account <admin>
+# hand the printed records to the customer's IT team, then later:
+dr desk sendgrid verify --server US --account <admin>
+```
+
+- `register` is idempotent - a second run returns the existing record and says
+  `already registered`. It does not change how any mail is sent today (see the
+  precedence note above), which is why it is Tier B: two-step token, no word gate.
+- **Four records, not three.** SendGrid returns three CNAMEs; the gateway appends
+  a DMARC TXT of its own. The `TYPE` column matters - telling a customer to add a
+  CNAME for the DMARC record is a step that cannot succeed.
+- `status` reads stored state and does **not** contact SendGrid, so it carries no
+  per-record verdicts and an unverified domain always reads as
+  `records_missing` there. Use `verify` for the authoritative check; `status` will
+  say so.
+- `verify` is not confirm-gated. It only refreshes state a server-side poller
+  refreshes every 15 minutes anyway, and it is the verb you run repeatedly while
+  waiting on a customer's DNS.
+- `VALID` of `-` means SendGrid has not reported on that record, which is **not**
+  the same as failing. It is always `-` for `dmarc`, which SendGrid never
+  validates.
+- `verification_state` is the field to branch on, not `is_verified`:
+  `not_registered`, `records_missing` (wait, or run verify), `records_invalid`
+  (the DNS is wrong - the response names which record and why), `verified`.
+- With several domains registered, `status` and `verify` target the **most
+  recently registered** one. Pass `--domain <d>` to name an older one. This
+  matters mid-migration, when the org has a verified old domain and a fresh
+  unverified one.
+
+## Opening a ticket
+
+```
+dr desk ticket create <team> --title "..." --requester-email someone@acme.com --server DEV
+# ... redeem the token ...
+```
+
+`<team>` takes a team id, a support email, or a team name - the same resolution
+`smtp set` uses. Everything else is a flag: `--description` / `--description-file`,
+`--priority urgent|medium|low`, `--ticket-type`, `--requester-name`,
+`--assigned-to`, `--contact-id`, `--due-date`, `--attach`.
+
+**`--attach <path>` (repeatable) is create-then-upload, not one call.** Desk has
+no endpoint that creates a ticket with files: the ticket is one request and each
+file is another (`POST /api/desk/v1/tickets/<id>/attachments/upload`). So the
+requester's confirmation email is published *before* the files exist, a failed
+upload exits non-zero naming which files landed, and retrying means attaching
+from the UI - re-running the command would open a second ticket and email the
+requester again.
+
+Extensions (`.pdf .xlsx .xls .docx .doc .csv .png .jpg .jpeg .gif`) and the 25 MB
+per-file cap are checked locally before the create, so a bad file costs no
+ticket, no email and no token. The cap is deployment-overridable server-side, so
+that check is an early failure, not a guarantee. The CLI also derives the
+content type from the extension - an untyped upload would be stored as
+`application/octet-stream` on both the row and the blob, permanently, where the
+web composer records the real type. An EXTENSIONLESS file is rejected locally
+even though the server would accept it (its check short-circuits on an empty
+suffix): there is no extension to derive a type from, and the web UI rejects it
+too.
+
+**The description is also posted as the requester's first message by default**
+(`--no-thread` opts out). `description` is a ticket column, but the UI's
+conversation pane renders the separate `messages` table - so without this a
+CLI-created ticket looks empty on screen even though the description stored
+fine. This mirrors desk-ai's own inbound handler, which sets `description` AND
+creates a message with the same body. It sends **no** email: the message is
+`direction: inbound`, and every send path is behind
+`not is_internal_note and direction == "outbound"`. Note `direction` is
+optional in desk-ai's schema and a non-note defaults to OUTBOUND, so omitting
+it would email the requester a second time - it is always sent explicitly.
+Attachments link to that message, so the FILES pane groups them as "Received".
+
+This does NOT clear the "requester is not linked to any record" banner:
+`requester_match_status` is assigned only in desk-ai's inbound handler, so
+requester matching never runs on the API create path at all. Use `--contact-id`.
+
+**`--json` becomes `{ticket, attachments}` when `--attach` was used** - so a
+partial failure is visible to a script. With no attachments it stays the bare
+ticket.
+
+Uploading is **team-scoped** (creating is org-scoped) and Desk answers **404, not
+403**, for a ticket the caller may not see. A routing rule that moves the new
+ticket to another team therefore makes the upload say "not found" for an id just
+printed; the CLI renders that as the team-access answer it is.
+
+**This is the one Desk verb that is not admin-only - but that does not mean you
+can skip `dr login-as`.** The route admits a caller who belongs to at least one
+Desk team in the org, or who is a platform admin. `SUPER_ADMIN`/`ADMIN` is not
+required the way it is for the onboarding verbs, but an integrations engineer's
+own identity in a customer org has no Desk team memberships either, so it 403s
+for that reason instead. The working identity in a customer org is still
+`dr login-as <customer-admin>` then `--account <that-email>`.
+
+The memberships are read from the monolith on every request, so a monolith
+outage produces the same 403 for a genuine team member. If the identity is right,
+retry before escalating.
+
+The org is still taken from the token, so `--server` / `--account` decide which
+customer gets the ticket.
+
+**It emails the requester.** Desk publishes a ticket-confirmation message to
+`--requester-email` off the same request, which is why the command is
+confirm-gated and why production keeps the interactive word gate. The ticket can
+be cancelled afterwards **in the Desk UI - this CLI has no cancel verb** - but
+that undoes the row, not the message. Use your own address when testing.
+
+If `<team>` is a numeric id, the CLI checks it against the org's teams first:
+`tickets.team_id` has no foreign key, so a typo'd id creates a ticket on no
+board that emails nobody, and the plan step would print it as a fact. That check
+needs the admin-only teams list, so when it is unavailable (non-admin identity,
+or the platform API is down) the command still runs and the plan says
+`NOT VERIFIED` with the reason rather than blocking - `ticket create` itself
+needs neither admin nor that list.
+
+Four things can come back different from what you sent, and none of them is the
+CLI dropping a flag - the command says so in its output when it happens:
+
+- `--assigned-to` forces the status to `to_do` rather than `unassigned`.
+- An omitted `--due-date` is back-filled from the SLA deadline the server
+  computes for that team and ticket type.
+- A routing rule can **move the ticket to another team**. The confirmation email
+  then leaves from the destination team's mailbox, not the one you named.
+- A routing rule can set the priority or the assignee - **but only for a flag you
+  did NOT pass.** desk-ai keys this off whether the field was present in the
+  request (`skip_priority` / `skip_assignment`), so passing `--priority` or
+  `--assigned-to` suppresses the corresponding rule for that ticket. That cuts
+  both ways: passing `--priority medium` is not the same as omitting it, because
+  it silences every Set-Priority rule.
+
+Use `--description-file` for anything longer than a sentence. A 50 000-character
+body in `argv` lands in shell history, and the pasted confirm command names the
+file rather than inlining the prose.
+## Clone a reference org's Desk into another org (`desk clone`, DR-52763)
+
+Demo provisioning: copy the reference demo org's Desk into an existing demo org
+so it shows the same tickets, ticket screens and overview, with the reference
+users "playing" the same parts. Everything is **match-or-create, nothing is
+deleted or overwritten**, so the command is safe to re-run on a target that
+already has people, teams and tickets.
+
+```
+# 0. Desk is dark in an org until its feature flags are on. Copy the source
+#    org's set: `dr features orgs list <source-org>` and look for `desk`.
+dr features orgs add 41 --flag desk__enable_product_v2 --flag desk__v1_5 \
+  --flag desk__ai_composer_v1_5 --flag desk_ai_mfe_enabled --server DEV-1 --account <you>
+# ... redeem the token ...
+dr login-as <target-org-admin> --server DEV-1
+dr desk clone --source-org 32 --target-org 41 --dry-run --server DEV-1 --account <target-org-admin>
+dr desk clone --source-org 32 --target-org 41 --server DEV-1 --account <target-org-admin>
+dr desk clone --source-org 32 --target-org 41 --confirm-token <token> --server DEV-1 --account <target-org-admin>
+```
+
+What it does, in order:
+
+1. **Users** (CLI, IT users API): every active source-org user, minus blocked
+   accounts, gets its e-mail moved to the target org's domain
+   (`ann@acme.com` -> `ann@demo-acme.com`). An existing target user with that
+   address is matched; otherwise the user is created with the same name and
+   role (`SUPER_ADMIN` becomes `ADMIN`), **no invite e-mail**. Domains come from
+   the organization records (`/api/it/organizations`), falling back to the most
+   common user e-mail domain only when the record is not readable;
+   `--source-domain` / `--target-domain` override both. **Demo orgs named like `demo.<name>.12.25` get `.com` appended**
+   (`ann@demo.brian.12.25.com`): the platform refuses an address whose last
+   label is numeric, exactly as it already names those orgs' support users. The
+   plan prints an `e-mail domain:` line when this happens; existing users on the
+   raw domain still match. Team support addresses follow the same rule. The
+   source **support user** is never created: it maps onto the target org's own
+   support user, so `support@<target>` joins the same teams it belongs to in the
+   reference org — that is the identity CS presents demos with, and without the
+   mapping it lands on the onboarding screen.
+2. **Teams + members** (desk-ai, through the monolith): source teams are matched
+   to target teams by name; missing ones are created with the same type and
+   the support address moved to the target domain — the platform registers the
+   new inbound mailbox and SendGrid domain as the team wizard would. Every
+   mapped member is added where missing.
+3. **Desk data** (desk-ai): tags, SLA, field configs (UDM mappings), routing
+   rules, contacts, tickets, messages, attachments, followers, audit history,
+   scheduled messages. Tickets already present in a target team are skipped
+   with their history, so a re-run never duplicates a conversation.
+
+Feature flags are per org and `desk clone` does **not** copy them (they are IT
+flags, not Desk data; an org created by the full `organizations export/import`
+does inherit the source's flags, a hand-made org does not). A target org without them shows no Desk entry at all, or
+the pre-v2 UI, and the clone looks broken when it is not. Enable them with your
+own IT identity **before** the clone — `features orgs add` is a normal
+two-step confirm — and check with `features orgs list <target-org>` that the
+flags now appear. The four above are the set on dev-1 at the time of writing;
+the source org's list is authoritative.
+
+Identity: run it as an impersonated **admin of the target org** (`dr login-as`);
+desk-ai accepts the impersonation token (or a `SUPER_ADMIN`) and refuses plain
+org admins, because the call reads another org's data. Your own account must
+have support access to the source org — that is what `can_login_as` uses to
+list its users; "no users visible in source org" means it does not.
+
+`--dry-run` skips the confirm gate, creates nothing on either side, and prints
+the user plan plus the team/data report desk-ai computes inside a rolled-back
+transaction. Without `--confirm-token` the real run prints the plan and stops.
+
+Not cloned: platform permission groups and data permissions (only role + team
+membership), UDM tables themselves (assumed present and identical in the
+target), attachment blobs that fail to copy (the row keeps the source URL and
+is counted in the report). Users are created without a password: demo personas
+never log in; the presenter impersonates.
+
+## Foot-guns
+
+- A `records_invalid` verdict is nearly always one of two customer-side causes:
+  a proxied CNAME (on Cloudflare it must be the grey cloud, not orange), or the
+  DNS provider appending the domain twice because the full hostname was pasted
+  into a field that wanted only the first label. The `next_action` text says so;
+  print it rather than re-wording it.
+- `manual_steps` in every response is the human part of onboarding with the
+  customer's own values already filled in. It is written server-side so both
+  paths say the same thing - relay it verbatim.
+- DNS propagation is usually minutes but can take 48 hours. `records_missing`
+  shortly after the customer says they are done is expected, not a failure.
+
+## Help Center
+
+Customer-facing setup docs live in the Datarails Help Center under the email /
+Desk folders - search with `dr kb search` before writing anything new for a
+customer.