zoodealio 0.3.1-dev.1641 → 0.4.0-dev.1648

package/README.md

@@ -132,7 +132,7 @@ Route IDs are GUIDs and are checked before any request is made.
 Write bodies come from `--body '<json>'`, `--body @file.json` or `--body -` (stdin). Where
 a body is trivial, convenience flags build it instead; use one or the other, not both.
 List commands accept `--page` and `--page-size`. `--if-match <etag>` sends optimistic
-concurrency on `properties update`, `offers accept` and `offers request-details`.
+concurrency on `properties update` and `comping start`.
 
 ## Commands
 
@@ -148,14 +148,16 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | `properties documents list\|add\|delete` | documents | same shape as photos |
 | `properties import-status <id> <importId>` | GET imports/{importId} | Photo and document imports |
 | `offers list` | GET Offers | `--property` required, `--status` |
-| `offers get <id>`, `offers history <id>` | GET | |
-| `offers accept <id>` | POST accept | `--yes` required; `--attributes <json\|@file>`, `--if-match` |
-| `offers request-details <id>` | POST request-details | `--if-match` |
+| `offers get <id>` | GET Offers/{id} | Read-only: `amount` for actual offers, `estimatedRange` for estimates |
 | `transactions get <id>` | GET Transactions/{id} | |
 | `transactions active` | GET Transactions/active | `--property` required |
-| `comping status <transactionId>` | GET Transactions/{id}/comping | |
+| `comping start <transactionId>` | POST Transactions/{id}/comping | `--if-match`; starts cash-offer comping |
+| `comping status <transactionId>` | GET Transactions/{id}/comping | `status` and `links` |
+| `ai-comping start <propertyId>` | POST Properties/{id}/ai-comping | Starts an AI Comping report; returns `{transactionId}` |
+| `ai-comping status <transactionId>` | GET Transactions/{id}/ai-comping | `status` (`running`, `ready`, `failed`), values, `offers`, `links` |
 | `team members`, `team get <id>`, `teams list` | GET Team | `--search`; `team members` also lists pending invites (`kind: "invite"`) |
 | `team invite` | POST Team/members | `--email` (+ `--first-name`, `--last-name`, `--team`, `--admin-team`) or `--body` |
+| `team join-codes list\|save\|delete` | GET, PUT, DELETE Team/join-codes | `save`: `--body` (create or update); `delete <id>` needs `--yes` |
 | `team remove <id>` | DELETE Team/members/{id} | `--yes` required |
 | `webhooks event-types\|list\|deliveries` | GET Webhooks | `deliveries`: `--subscription`, `--status` |
 | `webhooks create` | POST Webhooks | `--url` and `--event` (repeatable) or `--body` |
@@ -169,7 +171,7 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | `api <METHOD> <path>` | any `/openapi/...` | `--query k=v` (repeatable), `--body`; `DELETE` needs `--yes` |
 | `commands` | | Command catalogue as JSON |
 
-Destructive commands (`keys revoke`, `offers accept`, `team remove`, `properties photos delete`,
+Destructive commands (`keys revoke`, `team remove`, `team join-codes delete`, `properties photos delete`,
 `properties documents delete`, `webhooks rotate`, `webhooks delete`, and `api ... DELETE`)
 refuse to run without `--yes`, exit 2, and send nothing. `--dry-run` previews them
 without `--yes`, since it sends nothing either.
@@ -177,6 +179,27 @@ without `--yes`, since it sends nothing either.
 `api` accepts `Properties` or `/openapi/Properties`. Paths that are absolute URLs, contain
 `..`, or fall outside `/openapi/` are rejected.
 
+## Core flow and links
+
+Partners create properties, start comping, read amounts and send people to Zoodealio for
+everything else (terms, documents, acceptance). The loop:
+
+1. `properties create`, then `offers list --property <id>` for the estimated range.
+2. `transactions active --property <id>`, then `comping start <transactionId>`.
+3. Wait for the `comping.completed` webhook, or poll `comping status <transactionId>`.
+4. Read amounts with `offers list`; open the `links` for the rest.
+
+`comping status`, `ai-comping status` and transactions carry a `links` object:
+
+```json
+{ "links": { "agent": "https://.../properties/<id>/offer-reveal", "homeowner": "https://.../dashboard/<id>/<ref>?next=reveal" } }
+```
+
+`agent` is the agent's page for the transaction's current step. `homeowner` is the
+homeowner's sign-in link for the same step, or `null` when the property has no homeowner
+(for AI Comping, `null` until the agent shares the report). Offers are read-only and carry
+`amount` only (actual offers); there is no accept or request-details command.
+
 ## Examples
 
 ```sh
@@ -185,15 +208,18 @@ zoodealio properties list --search "Elm St" --state AZ
 zoodealio properties photos add <propertyId> --url https://example.com/front.jpg
 zoodealio properties import-status <propertyId> <importId>
 
-# Offers: list for a property, preview an accept, then accept
+# Offers (read-only): the estimated range, then actual amounts once comping is done
 zoodealio offers list --property <propertyId>
-zoodealio offers accept <offerId> --dry-run
-zoodealio offers accept <offerId> --yes
 
-# Transactions and comping
+# Transactions and comping: start, check, then hand the user the links
 zoodealio transactions active --property <propertyId>
+zoodealio comping start <transactionId>
 zoodealio comping status <transactionId>
 
+# AI Comping report
+zoodealio ai-comping start <propertyId>
+zoodealio ai-comping status <transactionId>
+
 # Team
 zoodealio team invite --email new@example.com --first-name Ada --team <teamId>
 
@@ -213,10 +239,10 @@ zoodealio api GET Properties --query pageSize=5
 - Run writes with `--dry-run` first and check the URL and body, then run them again
   without it.
 - `--yes` is a gate for explicit human intent. Pass it only when the person asked for that
-  destructive action (accepting an offer, removing a member, deleting or rotating a
+  destructive action (removing a member, deleting or rotating a
   webhook); do not add it to make an error go away.
 - For request body shapes run `zoodealio openapi`, which prints the partner OpenAPI document.
-- Prefer webhooks, or polling `comping status` and `import-status`, to long waits. The
+- Prefer webhooks, or polling `comping status`, `ai-comping status` and `import-status`, to long waits. The
   [developer docs](https://zoodealio.ai/developers#webhooks) cover events, signatures and delivery.
 
 ## Limits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zoodealio",
-  "version": "0.3.1-dev.1641",
+  "version": "0.4.0-dev.1648",
   "description": "Zoodealio command line tool: the partner API as JSON, built for people, scripts and AI agents",
   "license": "UNLICENSED",
   "repository": {

package/src/commands.js

@@ -1,5 +1,4 @@
 const { usage } = require('./errors');
-const { parseJsonArg } = require('./input');
 
 /**
  * @typedef {{name: string, type: 'string' | 'boolean', description: string, multiple?: boolean,
@@ -86,20 +85,20 @@ const COMMANDS = [
         flags: [str('property', 'Property id', { query: 'propertyId', required: true }), str('status', 'Offer status filter', { query: 'status' }), ...PAGING],
     }),
     cmd('offers get', 'Get one offer', 'GET', '/openapi/Offers/{id}', { args: [id('id', 'Offer id')] }),
-    cmd('offers history', 'Get an offer\'s revision history', 'GET', '/openapi/Offers/{id}/history', { args: [id('id', 'Offer id')] }),
-    cmd('offers accept', 'Accept an offer; returns the transaction', 'POST', '/openapi/Offers/{id}/accept', {
-        args: [id('id', 'Offer id')], destructive: true, body: 'optional', convenience: ['attributes'],
-        flags: [str('attributes', 'Homeowner-confirmed property attributes: JSON or @file'), IF_MATCH],
-        build: (f) => (f.attributes === undefined ? undefined : { attributes: parseJsonArg(f.attributes, '--attributes') }),
-    }),
-    cmd('offers request-details', 'Ask the agent for the offer\'s full breakdown', 'POST', '/openapi/Offers/{id}/request-details', {
-        args: [id('id', 'Offer id')], flags: [IF_MATCH],
-    }),
     cmd('transactions get', 'Get one transaction', 'GET', '/openapi/Transactions/{id}', { args: [id('id', 'Transaction id')] }),
     cmd('transactions active', 'Get a property\'s active transaction', 'GET', '/openapi/Transactions/active', {
         flags: [str('property', 'Property id', { query: 'propertyId', required: true })],
     }),
-    cmd('comping status', 'Get AI comping status for a transaction', 'GET', '/openapi/Transactions/{transactionId}/comping', {
+    cmd('comping start', 'Start comping for a transaction', 'POST', '/openapi/Transactions/{transactionId}/comping', {
+        args: [id('transactionId', 'Transaction id')], flags: [IF_MATCH],
+    }),
+    cmd('comping status', 'Get comping status and links for a transaction', 'GET', '/openapi/Transactions/{transactionId}/comping', {
+        args: [id('transactionId', 'Transaction id')],
+    }),
+    cmd('ai-comping start', 'Start an AI Comping report for a property', 'POST', '/openapi/Properties/{propertyId}/ai-comping', {
+        args: [id('propertyId', 'Property id')],
+    }),
+    cmd('ai-comping status', 'Get an AI Comping report\'s status, values, offers and links', 'GET', '/openapi/Transactions/{transactionId}/ai-comping', {
         args: [id('transactionId', 'Transaction id')],
     }),
     cmd('team members', 'List team members, including pending invites', 'GET', '/openapi/Team/members', {
@@ -123,6 +122,9 @@ const COMMANDS = [
     cmd('teams list', 'List teams', 'GET', '/openapi/Team/teams', {
         flags: [str('search', 'Free-text search', { query: 'search' }), ...PAGING],
     }),
+    cmd('team join-codes list', 'List workspace join codes', 'GET', '/openapi/Team/join-codes'),
+    cmd('team join-codes save', 'Create or update a join code', 'PUT', '/openapi/Team/join-codes', { body: 'required', flags: [BODY] }),
+    cmd('team join-codes delete', 'Delete a join code', 'DELETE', '/openapi/Team/join-codes/{id}', { args: [id('id', 'Join code id')], destructive: true }),
     cmd('webhooks event-types', 'List webhook event types', 'GET', '/openapi/Webhooks/event-types'),
     cmd('webhooks list', 'List webhook subscriptions', 'GET', '/openapi/Webhooks'),
     cmd('webhooks create', 'Create a webhook subscription', 'POST', '/openapi/Webhooks', {