@planescrm/sdk 0.55.0 → 0.72.0

package/README.md

@@ -44,7 +44,8 @@ Resources: `opportunities`, `customers`, `properties`, `calendarEvents`,
 `contracts`, `jobs`, `estimates`, `invoices`, `inventory`, `contacts`,
 `activities`, `communications`, `gmail`, `documents`, `tags`, `tasks`,
 `customFields`, `recordViews`, `modules`, `plan`, `me`, `roles`, `contactSequences`,
-`enrollments`, `workflows`, `billingSchedules`.
+`enrollments`, `workflows`, `billingSchedules`, `webhookSubscriptions`, `users`,
+`teams`.
 
 ### Breaking changes (0.43.0)
 
@@ -200,8 +201,11 @@ if (res.workflow_trigger.status === 'failed') {
 }
 ```
 
-`status` is `fired`, `skipped` (no transition set) or `failed` (with a
-`reason` and `message`; the tenant's admins also get a notification).
+`status` is `fired`, `skipped` or `failed` (with a `reason` and `message`; the
+tenant's admins also get a notification). A skip's `reason` is
+`no_completion_transition` (none set) or, since 0.59.0,
+`handled_by_pipeline_rule`: the record's pipeline rule moves it after the
+request, so the event's own step didn't run.
 Since 0.55.0 a `fired` trigger carries `to_stage: { id, name }`, the stage the
 transition moved the record to; `tasks.complete(id)` returns the same
 `workflow_trigger`:
@@ -313,6 +317,144 @@ await client.roles.updateGrants('sales', {
 const { data, cursor } = await client.roles.history({ role: 'sales', limit: 20 });
 ```
 
+### Lists (0.64.0)
+
+`client.lists` covers every `/lists` route: find, read, create, rename or
+redefine, delete, add and remove members, read recipients, and export.
+`list()` returns a bare array, newest first, each list with `member_count`.
+A list with `managed_by` set (owned by an integration) refuses member and
+definition changes; it can still be renamed.
+
+```ts
+const all = await client.lists.list();
+const promo = all.find((l) => l.name === 'Fall promo');
+
+await client.lists.addMembers(promo.id, [{ entity_type: 'customer', entity_id: customerId }]);
+await client.lists.removeMembers(promo.id, [{ entity_type: 'customer', entity_id: otherId }]);
+
+const { data: people } = await client.lists.getRecipients(promo.id, { page: 1, limit: 50 });
+await client.lists.update(promo.id, { name: 'Fall promo 2026' });
+await client.lists.delete(promo.id); // soft delete; the records are untouched
+```
+
+### Custom field definitions, webhook subscriptions, users and teams (0.72.0)
+
+**Custom field definitions** can now be configured, not just read. With the
+admin grant on custom field definitions:
+
+```ts
+const field = await client.customFields.create({
+  entityType: 'customer',
+  fieldKey: 'crm_id',            // lower_snake_case; can't change later
+  label: 'CRM ID',
+  fieldType: 'text',
+  searchable: true,
+});
+await client.customFields.update(field.id, { label: 'External CRM ID' });
+await client.customFields.deactivate(field.id); // hidden; stored values stay valid
+```
+
+`listAll` and `get` read definitions through the same admin route. Definitions
+can be created for contacts, customers and opportunities. Jobs, vendors and
+agents get a 400 until those records can hold values.
+
+**Webhook subscriptions** (`client.webhookSubscriptions`; the `open_api`
+feature and admin grants): `create` (returns the `whsec_` signing secret once),
+`list`, `get`, `update`, `delete`, `test` (sends one signed test event now),
+`rotateSecret`, `listDeliveries` and `retryDelivery`. `client.webhooks` is still
+the event router for verifying and handling deliveries.
+
+**Users and teams, read-only:** `client.users.list`, `client.users.directory`
+(ids, names and roles of active users, readable by every role),
+`client.users.getWorkingHours`, `client.teams.list` and `client.teams.get`.
+Inviting, editing and removing users, and changing teams, stay in the app.
+
+### Records: estimates, jobs, contracts, invoices, customers, calendar events (0.72.0)
+
+- **Estimates:** line items (`createLineItem`, `updateLineItem`, `deleteLineItem`,
+  `reorderLineItems`), `updateStatus`, and pipeline moves (`getWorkflow`,
+  `listTransitions`, `transition`).
+- **Jobs:** pipeline moves (`getWorkflow`, `listTransitions`, `transition`).
+  Material use is on `inventory`: `recordJobConsumption`, `listJobConsumption`,
+  `returnFromJob`, `getJobMaterialVariance`.
+- **Contracts:** `createForSubject`, `createFlat`, `submit`, `approve`, `cancel`,
+  `reopen`, `send`, `createChangeOrder`, `listChangeOrders`, `downloadPdf`.
+- **Invoices:** `listPayments`, `getPaymentRecordingSettings` (reads only).
+- **Customers:** `convertToCompany`. **Calendar events:** `cancel`,
+  `addParticipant`, `updateParticipantStatus`.
+
+`contracts.send()` emails the signer a signing link. A `transition()` runs the
+actions the tenant attached to that move, which can include sending email or
+an invoice. None of these take an idempotency key, so retrying after a timeout
+can repeat the email or the actions.
+
+### Service schedules (0.71.0)
+
+`client.serviceSchedules` now covers every `/service-schedules` route: `list`,
+`get`, `create`, `update`, `previewUpdate`, `setStatus`, `delete`,
+`previewConflicts`, and the dispatch settings (`getCrewRoles`, `setCrewRoles`,
+`listCrew`, `setCrewHomeAddress`).
+
+Changing a schedule's cadence, time, crew, duration or horizon regenerates the
+visits already on the calendar, from today. A visit
+someone changed (moved, re-crewed, confirmed or started, past its first stage,
+invoiced or marked do-not-bill) is never touched; it comes back under
+`protected` with its reasons.
+
+```ts
+const edit = { dtstart: '2026-12-03T09:00:00-06:00' }; // move to Thursdays
+const preview = await client.serviceSchedules.previewUpdate(scheduleId, edit);
+// { removed: 8, added: 8, updated: 0, protected: [...] }
+const { regeneration } = await client.serviceSchedules.update(scheduleId, edit);
+```
+
+### Tag merge (0.70.0)
+
+`client.tags.merge(winnerId, loserId)` folds a duplicate tag into another: every record tagged with the loser moves to the winner, and the loser is deleted.
+
+### Opportunity pipeline moves (0.69.0)
+
+```ts
+const { transitions } = await client.opportunities.listTransitions(oppId);
+await client.opportunities.transition(oppId, { transition_id: transitions[0].id as string, notes: 'Quote sent' });
+const workflow = await client.opportunities.getWorkflow(oppId); // stage + history
+```
+
+A move runs the stage's automations, exactly as the stage button in Planes does
+(they can send the customer a contract or an invoice).
+
+### Properties (0.68.0)
+
+`client.properties` gains `getForCustomer(customerId, id)` (404 if the property
+isn't that customer's) and `geocode(id)`, which queues a fresh geocode.
+
+### Lead sources (0.67.0)
+
+`client.leadSources` lists, creates, updates and deletes lead sources. A
+lead source's `key` is what a customer's `source` takes:
+
+```ts
+const sources = await client.leadSources.list(); // active ones, in display order
+await client.customers.update(customerId, { source: sources[0].key });
+```
+
+### Contact links, roles and pipeline (0.66.0)
+
+`client.contacts.get(id)` returns a contact with its channels and active links.
+The rest of the contact surface:
+
+```ts
+await client.contacts.listLinks(contactId);            // active and ended links (history)
+await client.contacts.addLink(contactId, { targetType: 'customer', targetId, role: 'GM' });
+await client.contacts.updateLink(contactId, linkId, { endedAt: new Date().toISOString() }); // end a link
+await client.contacts.listRoles();                     // roles in use, for a picker
+
+await client.contacts.startWorkflow(contactId);        // opt into the relationship pipeline
+const wf = await client.contacts.getWorkflow(contactId); // stage + available transitions
+await client.contacts.transition(contactId, transitionId);
+await client.contacts.getWorkflowHistory(contactId);
+```
+
 ### Contact sequences
 
 `client.contactSequences.list()` returns the tenant's published contact