@planescrm/sdk 0.4.0 → 0.55.0

package/README.md

@@ -1,14 +1,19 @@
-# @planes/sdk
+# @planescrm/sdk
 
 TypeScript SDK for the [Planes CRM](https://planescrm.com) platform — a typed API
 client, an ergonomic webhook router, OAuth helpers, and an action-handler server
 for building agents.
 
-> **Not yet published.** `@planes/sdk` is currently a private workspace package —
-> it is **not** on npm. Consume it from within this monorepo as a workspace
-> dependency (`"@planes/sdk": "workspace:*"`), or request access from the Planes
-> team. The `npm install @planes/sdk` examples below describe the intended
-> published surface once publishing is enabled.
+```bash
+npm install @planescrm/sdk
+```
+
+**Self-contained types (0.52.1).** The built package imports only Node builtins
+and its own dependencies — never the private `@blueprint/shared`. Types the API
+shares are mirrored under `src/types/*-types.ts` and checked against shared at
+compile time by `*.parity.ts` files, which are not reachable from `index.ts`.
+`build` runs `scripts/check-shipped-imports.mjs` after `tsup` and fails if
+`dist/` or a shipped source file imports anything else.
 
 ## Client
 
@@ -16,7 +21,7 @@ for building agents.
 exactly **one** authentication mode.
 
 ```ts
-import { PlanesClient } from '@planes/sdk';
+import { PlanesClient } from '@planescrm/sdk';
 
 // 1. A pre-obtained OAuth access token (not auto-refreshed).
 const client = new PlanesClient({ accessToken: 'tok_...' });
@@ -36,7 +41,413 @@ const opp = await client.opportunities.get('opp_123');
 ```
 
 Resources: `opportunities`, `customers`, `properties`, `calendarEvents`,
-`contracts`, `jobs`, `estimates`, `invoices`, `inventory`.
+`contracts`, `jobs`, `estimates`, `invoices`, `inventory`, `contacts`,
+`activities`, `communications`, `gmail`, `documents`, `tags`, `tasks`,
+`customFields`, `recordViews`, `modules`, `plan`, `me`, `roles`, `contactSequences`,
+`enrollments`, `workflows`, `billingSchedules`.
+
+### Breaking changes (0.43.0)
+
+Twenty methods called routes the API doesn't serve. Every old call failed with
+a 404 or 405, so no working integration depended on them. Each one now follows
+the real route, and a method the API doesn't have is gone, so calling it is a
+compile error instead of a runtime 404.
+
+| Resource | Before (never worked) | Now |
+|---|---|---|
+| `properties` | `list(params)`, `create(body)`, `update(id, body)` (PATCH), `delete(id)` on `/properties` | `list(customerId, params)`, `create(customerId, body)`, `update(customerId, id, body)` (PUT), `delete(customerId, id)` on `/customers/{customerId}/properties`. `get(id)` is unchanged (`GET /properties/{id}`). |
+| `jobs` | `list`, `get`, `create`, `update` (PATCH), `delete` on `/jobs` | `list(opportunityId, params)`, `get(opportunityId, id)`, `create(opportunityId, body)`, `update(opportunityId, id, body)` (PUT), `delete(opportunityId, id)` on `/opportunities/{opportunityId}/jobs`. `listForOpportunity()` and `getTradeCoverage()` are unchanged. |
+| `estimates` | `list`, `get`, `create`, `update` (PATCH), `delete` on `/estimates` | `list(jobId, params)`, `get(jobId, id)`, `create(jobId, body)`, `update(jobId, id, body)` (PUT), `delete(jobId, id)` on `/jobs/{jobId}/estimates`. `listForOpportunity()` is unchanged. |
+| `inventory` | CRUD on `/inventory/items`, `update` sent PATCH | Same methods on `/admin/inventory/items`; `update` sends PUT. |
+| `opportunities` | `update(id, body)` sent PATCH | `update(id, body)` sends PUT; the body is typed `UpdateOpportunityDto`. |
+| `tasks` | `delete(id)` | Removed (there is no delete route). Use `cancel(id)`; `reopen(id)` brings a task back. |
+| `tags` | `get(id)` | Removed (there is no single-tag read). Use `list()` or `getEntities(id)`. |
+
+New request types, mirroring the API's validation schemas: `CreatePropertyDto`,
+`UpdatePropertyDto`, `PropertyListParams`, `CreateJobDto`, `UpdateJobDto`,
+`CreateEstimateDto`, `UpdateEstimateDto`, `CreateInventoryItemDto`,
+`UpdateInventoryItemDto`, `InventoryItemListParams`, `UpdateOpportunityDto`.
+
+```ts
+const { data: properties } = await client.properties.list('cust_123');
+const job = await client.jobs.create('opp_123', { tradeId: 'trade_123' });
+await client.estimates.update('job_123', 'est_123', { taxRate: 0.0825 });
+await client.tasks.cancel('task_123');
+```
+
+### Invoices
+
+`client.invoices.list({ status, customerId, page, limit })` returns typed
+`InvoiceListItemDto` rows. Each row carries `customerName` — the company name
+for a company customer, "First Last" for a person — so a list view needs no
+follow-up `customers.get()` per row:
+
+```ts
+const { data } = await client.invoices.list({ status: 'sent' });
+data.forEach((inv) => console.log(inv.invoiceNumber, inv.customerName, inv.balance));
+```
+
+### Consent state (0.33.0)
+
+Every contact channel the API returns (`contacts.get`, `contacts.list({ include: ['channels'] })`,
+channel create/update) and `GET /customers/:id` / `PUT /customers/:id` carry a `consent`
+object (`ConsentStateDto`): the record's own `marketing_opt_out` / `dnc` flags,
+`effective_opted_out` (`marketing_email` / `sms` / `call`) — the by-address verdict every send
+honours, which can be true while the record's own flag is false because another record with the
+same address holds the opt-out — and `last_change` (`{ outcome, source, at, scope }` or `null`).
+
+```ts
+const { data } = await client.contacts.list({ customer_id: customerId, include: ['channels'] });
+for (const ch of data.flatMap((c) => c.channels ?? [])) {
+  if (ch.consent.effective_opted_out.marketing_email && !ch.consent.marketing_opt_out) {
+    console.log(ch.value, 'is opted out via another record', ch.consent.last_change?.source);
+  }
+}
+`client.invoices.downloadPdf(id)` (0.36.0) returns the invoice PDF as an
+`ArrayBuffer`. A sent invoice returns the copy stored when it was sent, and a
+draft renders on demand with a DRAFT watermark:
+
+```ts
+import { writeFile } from 'node:fs/promises';
+await writeFile('INV-0001.pdf', Buffer.from(await client.invoices.downloadPdf(invoiceId)));
+### Overdue invoices (0.35.0)
+
+`client.invoices.listOverdue({ minDays, customerId, page, limit })` returns
+sent / partially paid invoices past their due date, most overdue first, with
+`daysOverdue` and `lastOffsetReached`; `client.invoices.overdueSummary()`
+returns `{ count, total }`. A daily sweep emits the `invoice.overdue` webhook
+event (typed `InvoiceOverdueEvent`) once per invoice at each of the company's
+offsets — days after the due date, default `[3, 7, 14]`, read and set (admin)
+with `client.invoiceSettings.getOverdueOffsets()` / `setOverdueOffsets([...])`:
+
+```ts
+const { data } = await client.invoices.listOverdue({ minDays: 7 });
+const { count, total } = await client.invoices.overdueSummary();
+await client.invoiceSettings.setOverdueOffsets([5, 10, 30]); // 1–90 days, up to 5
+```
+
+Invoice emails attach that stored copy (as `INV-0001.pdf`) unless an admin turns
+it off: `client.invoiceSettings.setAttachPdf(false)` / `getAttachPdf()` (0.39.0;
+the write needs Update Tenant).
+
+Payment reminders (0.41.0, admin only): `client.invoiceReminders.list()` returns
+the rules and the overdue offsets (a rule at an offset the sweep never emits is
+`willNeverFire`); `update(rules)` replaces the whole set (unknown placeholders are
+a 422 `REMINDER_TEMPLATE_INVALID`); `preview({ subject, body, invoiceId? })`
+renders exactly what would send, without sending:
+
+```ts
+await client.invoiceReminders.update([
+  { offsetDays: 7, enabled: true, subject: 'Invoice {{invoiceNumber}} is past due', body: 'Hi {{customerName}}, {{amountDue}} was due {{dueDate}}.' },
+]);
+const { subject, body } = await client.invoiceReminders.preview({ subject: '…', body: '…', invoiceId });
+```
+
+### Billing schedules (0.32.0)
+### Billing schedules (0.32.0; line versions 0.34.0; adjustments 0.38.0; autopay summary 0.46.0)
+
+`client.billingSchedules` manages recurring invoices (`/admin/billing-schedules`,
+invoicing module). Fields are snake_case, money is a 2-decimal string, and
+dates are `YYYY-MM-DD`:
+
+```ts
+const schedule = await client.billingSchedules.create({
+  customer_id: 'cus_123',
+  name: 'Monthly maintenance',
+  cadence: 'monthly',
+  start_date: '2026-11-01', // a past date also needs backfill: 'skip' | 'draft'
+  lines: [{ description: 'Lawn care', quantity: '1', unit_price: '120.00' }],
+}); // timezone defaults to the tenant's
+
+await client.billingSchedules.preview(schedule.id, { count: 12 }); // next 12 periods
+// A price change from a date: periods starting on or after it bill the new lines.
+await client.billingSchedules.update(schedule.id, {
+  lines: [{ description: 'Lawn care', quantity: '1', unit_price: '135.00' }],
+  effective_from: '2027-01-01',
+});
+await client.billingSchedules.listVersions(schedule.id); // line version history
+// A one-off credit (or charge) on the next invoice only — no automatic proration.
+const credit = await client.billingSchedules.addAdjustment(schedule.id, {
+  description: 'Credit: 10 days not serviced',
+  amount: '-40.00',
+});
+await client.billingSchedules.listAdjustments(schedule.id); // pending + consumed
+await client.billingSchedules.cancelAdjustment(schedule.id, credit.id); // only while pending
+await client.billingSchedules.periods(schedule.id, { status: 'failed' }); // the period ledger
+await client.billingSchedules.needsReview(); // tenant-wide queue
+await client.billingSchedules.autopaySummary(); // { data: { autopaySchedules, customers, savedCards } } before a Stripe disconnect
+await client.billingSchedules.generateNow(schedule.id); // bill the current due period now
+await client.billingSchedules.skipPeriod(schedule.id, '2026-12-01', { reason: 'Away' });
+await client.billingSchedules.regeneratePeriod(schedule.id, '2026-11-01'); // after a void
+await client.billingSchedules.pause(schedule.id); // also resume(id), end(id)
+```
+
+Also `list({ customer_id, status, page, limit })`, `get(id)` (with
+`upcoming_periods`), `update(id, patch)` (`lines` replaces every line) and
+`delete(id)` (only a schedule that never invoiced).
+
+### Completing calendar events (0.44.0)
+
+`client.calendarEvents.complete(id, { completion_notes? })` marks an event
+completed and runs its "on complete" transition, best-effort. The event is
+always completed; `workflow_trigger` says whether the transition ran:
+
+```ts
+const res = await client.calendarEvents.complete('evt_123');
+if (res.workflow_trigger.status === 'failed') {
+  // e.g. reason 'not_valid_from_current_stage' or 'wrong_pipeline'
+  console.warn(res.workflow_trigger.message);
+}
+```
+
+`status` is `fired`, `skipped` (no transition set) or `failed` (with a
+`reason` and `message`; the tenant's admins also get a notification).
+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`:
+
+```ts
+const { workflow_trigger } = await client.tasks.complete('task_123');
+if (workflow_trigger.status === 'fired') console.log(`Moved to ${workflow_trigger.to_stage?.name}`);
+```
+
+Actions on that transition run afterwards, so a chained transition may move the
+record again later; `to_stage` doesn't report that later move. Creating
+or updating an event with a `completion_workflow_transition_id` from a pipeline
+other than its linked record's is rejected with a 422
+`COMPLETION_TRANSITION_WRONG_PIPELINE`.
+
+### Updating recurring calendar events (0.54.0)
+
+`client.calendarEvents.update(id, patch, { editMode })` chooses which
+occurrences of a recurring event change: `this` (only this occurrence, the
+default), `this_and_future` (splits the series here) or `all` (the whole
+series). It is sent as the `recurrence_edit_mode` query parameter and ignored
+for one-time events. `this` on a series master is a 400 `INVALID_EDIT_MODE`.
+
+```ts
+await client.calendarEvents.update('evt_123', { starts_at: '2026-11-02T15:00:00' }, { editMode: 'this_and_future' });
+```
+
+A blank `recurrence_rule` in the patch means "doesn't repeat": it is ignored
+rather than stored, so it never changes an existing series.
+
+### Recently viewed
+
+`client.recordViews.touch({ entity_type, entity_id })` records that the calling
+user opened a customer / contact / opportunity / job (idempotent; 204 even for
+an id that no longer exists). `client.recordViews.recent({ limit })` returns
+that user's newest views. The four list calls accept `sort_by: 'recent'` —
+the caller's most recently opened records first, never-viewed last
+(`sort_order` is ignored for it):
+
+```ts
+await client.recordViews.touch({ entity_type: 'customer', entity_id: 'cus_123' });
+const { data } = await client.customers.list({ sort_by: 'recent' });
+const jobs = await client.jobs.listForOpportunity('opp_123', { sort_by: 'recent' });
+```
+
+### Module status
+
+`client.modules.list()` returns `{ moduleKey, isActive }` for every registered
+module in the caller's tenant (any role; read-only). A module that was never
+activated reads `isActive: false`:
+
+```ts
+const modules = await client.modules.list();
+const contactsOn = modules.some((m) => m.moduleKey === 'contacts' && m.isActive);
+```
+
+### Plan
+
+`client.plan.get()` returns the caller tenant's plan (any role; read-only):
+`planKey`, `label`, `billingStatus`, `planSource`, `trialEndsAt`,
+`billingInterval`, `priceLockedUntil`, and the plan's ceiling — the `modules`
+and `features` it may enable, `includedFullSeats`, `crewSeatsAllowed`,
+`monthlyAiCredits` and `storageGb`. A ceiling is not activation: check
+`client.modules.list()` for what is switched on. Plans change in Settings →
+Billing, not through the API.
+
+```ts
+const plan = await client.plan.get();
+const canInvoice = plan.modules.includes('invoicing');
+```
+
+### Caller abilities
+
+`client.me.abilities()` returns the caller's effective ability — the exact
+rules the server enforces — as `{ role, actingRole?, version, rules }`.
+`rules` are CASL packed rules; for an API key, `actingRole` is the acting
+agent's live role and the rules are the key role ∩ that role. `version`
+matches the `X-Planes-Abilities-Version` header on every authenticated
+response, so a changed header means refetch:
+
+```ts
+import { createMongoAbility } from '@casl/ability';
+import { unpackRules } from '@casl/ability/extra';
+
+const { role, rules } = await client.me.abilities();
+const ability = createMongoAbility(unpackRules(rules));
+ability.can('delete', 'Customer');
+```
+
+### Roles (admin only)
+
+`client.roles` manages Settings → Roles (0.19.0). Every call needs an admin
+caller — any other role gets a 403 `FORBIDDEN_BY_ROLE`. `list()` returns
+`{ data: [{ key, label, tunable, userCount, changeCount }] }`; `get(key)` one
+role's matrix (`{ key, label, tunable, summary, version, rows: [{ rowId,
+cells: [{ action, subject, value, default, tier, locked }] }] }`).
+`updateGrants(key, body)` sends sparse cell changes (`effect: 'allow' | 'deny' |
+'default'`); granting a money action (approve, mark paid, correct, payments)
+needs `confirm: true` and a `reason`, and passing the `version` you read as
+`baseVersion` turns a concurrent edit into a 409. `reset(key)` returns a role
+to the Planes defaults; `history({ role, cursor, limit })` pages the change log:
+
+```ts
+const sales = await client.roles.get('sales');
+await client.roles.updateGrants('sales', {
+  changes: [{ action: 'delete', subject: 'Customer', effect: 'allow' }],
+  baseVersion: sales.version,
+});
+const { data, cursor } = await client.roles.history({ role: 'sales', limit: 20 });
+```
+
+### Contact sequences
+
+`client.contactSequences.list()` returns the tenant's published contact
+sequences as `{ data: [{ id, name, description }], meta: { total } }`
+(name-sorted, max 100), readable by any role that can enroll a contact. Each
+`id` is the sequence's lineage root — the `workflow_id` that
+`POST /contacts/:id/enrollments` accepts:
+
+```ts
+const { data: sequences } = await client.contactSequences.list();
+```
+
+### Sequence enrollments
+
+`client.enrollments` enrolls a contact in a sequence (the `id` from
+`contactSequences.list()`), lists a contact's enrollments, and exits one:
+
+```ts
+const enrollment = await client.enrollments.enroll(contactId, sequences[0].id);
+// 409 if already active in that sequence; 422 if it has no published version
+
+const active = await client.enrollments.list(contactId, { status: 'active' });
+// bare array, newest first — each row carries sequenceName + currentStageName
+
+await client.enrollments.exit(enrollment.id); // reason 'manual'; idempotent
+```
+
+### Workflow version stages
+
+`client.workflows.getStages(workflowId)` returns the ordered stages of one
+workflow version — `{ id, name, entityType, version, status, stages: [{ id,
+name, color, icon, sortOrder, isInitial, isTerminal }] }`. Pass a record's
+instance `workflowId` to draw its progress against the version it is pinned
+to, even an archived one after a newer version was published. Readable by any
+role that can read the workflow's record type (403 otherwise; 404 for an
+unknown or draft id):
+
+```ts
+const { stages } = await client.workflows.getStages(instance.workflowId);
+```
+
+A stage's `color` is a hex code or `null`. The API only accepts `#RGB` or
+`#RRGGBB` when a stage is written, and stores it as uppercase `#RRGGBB`.
+A stage saved before that rule may still hold some other string, so check
+the value before using it as a CSS colour.
+
+### Workflow transition summaries
+
+`client.workflows.listTransitions({ entityTypes, workflowId })` returns
+`{ transitions: [{ id, name, from_stage_name, to_stage_name, workflow_name,
+entity_type, workflow_id, workflow_version, lineage_workflow_id,
+automatic_only }] }`. With no `workflowId` it lists every published
+workflow's transitions; with one it lists that version's, published or
+archived, so a record pinned to an older version gets its own steps (an
+unknown, draft or other-tenant id returns an empty list). `lineage_workflow_id`
+is the same for every version of one pipeline. Both filters together are an
+AND. Only pipelines whose record type the caller can read are listed (the
+same rule as `getStages`): a `workflowId` of a type the key's role can't read
+returns an empty list, not 403, and an unreadable type in `entityTypes` is
+dropped:
+
+```ts
+const { transitions } = await client.workflows.listTransitions({ workflowId: instance.workflowId });
+const manual = transitions.filter((t) => !t.automatic_only);
+```
+
+### Workflow event rules (0.51.0)
+
+`client.workflows.eventRules(workflowId)` manages a workflow's "advance
+automatically when…" rules on the admin workflow API (manage Workflow + the
+`workflow_builder` feature): `list()`, `create(input)`, `update(ruleId, input)`
+and `delete(ruleId)`. A rule fires `transitionRef` (stage NAMES, resolved
+against the version each record is pinned to) when a related contract, invoice
+or calendar event emits `eventType` and its `changes` match `when`. Any
+version's id works; rules are keyed by the workflow's lineage root, so they
+survive a publish. `list()` is a bare array, newest first; `delete()` is a soft
+delete returning `{ id }`.
+
+Since 0.53.0 a rule carries exactly `id`, `workflowId`, `eventType`, `when`,
+`transitionRef`, `enabled`, `createdAt` and `updatedAt` (no `tenantId`,
+`createdBy` or `deletedAt`), and `update`/`delete` only reach a rule through an
+id of its own pipeline (any version); another pipeline's id is a 404
+`EVENT_RULE_NOT_FOUND`. A path id that isn't a uuid is a 400.
+
+```ts
+const rules = client.workflows.eventRules(workflowId);
+
+// Advance when the contract is sent.
+await rules.create({
+  eventType: 'contract.status_changed',
+  when: { status: { new: 'sent' } },
+  transitionRef: { from_stage_name: 'Estimate', to_stage_name: 'Contract Sent' },
+});
+
+// Advance when an event is booked. Creation types carry no `changes`, so the
+// only matcher is `when: {}` (see WORKFLOW_EVENT_RULE_MATCH_ALL_EVENT_TYPES).
+const booked = await rules.create({
+  eventType: 'calendar_event.created',
+  when: {},
+  transitionRef: { from_stage_name: 'New', to_stage_name: 'Booked' },
+});
+
+await rules.update(booked.id, { enabled: false }); // only the fields sent change
+await rules.delete(booked.id);
+```
+
+Event types: `WORKFLOW_EVENT_RULE_EVENT_TYPES` (`contract.status_changed`,
+`invoice.status_changed`, `calendar_event.status_changed`,
+`calendar_event.created`). A body the server rejects is a 400
+`VALIDATION_FAILED`; an unknown workflow is 404 `WORKFLOW_NOT_FOUND`, an
+unknown or deleted rule 404 `EVENT_RULE_NOT_FOUND`.
+
+### Job trade coverage
+
+`client.jobs.getTradeCoverage()` returns every active trade with whether a job
+can be created under it — `{ trades: [{ tradeId, name, hasWorkflow }] }`,
+ordered by name. `hasWorkflow` is true when a published job workflow resolves
+for the trade (its own or the generic one); creating a job under a trade with
+`hasWorkflow: false` returns 422 `WORKFLOW_NOT_CONFIGURED`. Readable by any
+role that can create jobs (403 otherwise):
+
+```ts
+const { trades } = await client.jobs.getTradeCoverage();
+const creatable = trades.filter((t) => t.hasWorkflow);
+```
+
+### Estimates across an opportunity
+
+`client.estimates.listForOpportunity(opportunityId, { status, page, limit })`
+returns every estimate across all of the opportunity's jobs in one request
+(newest first, each row carrying `jobId`; `limit` max 100):
+
+```ts
+const { data } = await client.estimates.listForOpportunity('opp_123', { limit: 100 });
+```
 
 ### Errors
 
@@ -44,7 +455,7 @@ Every failure throws a subclass of `PlanesError`, each carrying `status` and
 `code`:
 
 ```ts
-import { PlanesError, RateLimitError, ValidationError } from '@planes/sdk';
+import { PlanesError, RateLimitError, ValidationError } from '@planescrm/sdk';
 
 try {
   await client.opportunities.get('missing');
@@ -93,7 +504,7 @@ Use the OAuth helpers to drive the login redirect and exchange the returned code
 for tokens.
 
 ```ts
-import { buildAuthorizeUrl, exchangeCode } from '@planes/sdk';
+import { buildAuthorizeUrl, exchangeCode } from '@planescrm/sdk';
 
 const baseUrl = 'https://api.planescrm.com/api/v1';
 
@@ -115,7 +526,7 @@ const tokens = await exchangeCode({
 });
 
 // 3. Seed an OAuth-managed client so refreshes happen automatically.
-import { PlanesClient, MemoryTokenStorage } from '@planes/sdk';
+import { PlanesClient, MemoryTokenStorage } from '@planescrm/sdk';
 
 const client = new PlanesClient({
   clientId: process.env.PLANES_CLIENT_ID!,
@@ -135,7 +546,7 @@ gives a chainable builder; call `registerAction(type, handler)` per action and
 `listen()` to start.
 
 ```ts
-import { createAgentApp } from '@planes/sdk';
+import { createAgentApp } from '@planescrm/sdk';
 
 createAgentApp()
   .registerAction('enrich-opportunity', async (ctx) => {