@masonlandcattle/servicetitan-sdk 0.8.0 → 0.9.0

package/README.md

@@ -10,6 +10,11 @@ A pragmatic ServiceTitan API client with:
 - Broad tenant API namespace coverage across the current ServiceTitan developer portal
 - Exported TypeScript helper types for better IntelliSense when using the SDK
 
+The package supports both:
+
+- a namespaced client via `createClient(...)`
+- direct functional imports per namespace when preferred
+
 ### Release status
 
 Current release focus:
@@ -19,6 +24,24 @@ Current release focus:
 - Added missing documented resource modules and helpers
 - Expanded exported TypeScript helper types to improve IntelliSense
 
+Recommended release posture for the current line:
+
+- `0.9.x` is the stabilization phase after the broad OpenAPI alignment pass
+- the current public surface is intended to be much closer to the local OpenAPI specs than earlier releases
+- future breaking changes should mostly be reserved for upstream ServiceTitan API changes or clear correctness fixes
+
+### Repo notes
+
+If you are editing this SDK with Codex or another coding agent, use [`AGENTS.md`](./AGENTS.md) as the repo-specific guide.
+
+The short version:
+
+- local OpenAPI JSON files are the source of truth
+- breaking changes are acceptable when the schema and SDK disagree
+- prefer namespace-specific types over generic placeholders
+- keep [`src/types/resources.ts`](./src/types/resources.ts) for shared base helpers only
+- run `npm run build` after changes
+
 ### Install
 
 ```bash
@@ -64,6 +87,27 @@ await st.jpm.createJobNote(123456, { text: "Hello from SDK", pinToTop: true });
 const materials = await st.pricebook.listMaterials({}, { all: true, pageSize: 500 });
 ```
 
+### Important behaviors
+
+- Local OpenAPI JSON files in [`ServiceTitanOpenAPIJson`](./ServiceTitanOpenAPIJson) are the source of truth for this SDK.
+- Breaking changes are allowed when the documented ServiceTitan contract and the previous SDK surface disagree.
+- Export feeds generally use `{ from, includeRecentChanges }` continuation params and return `{ data, hasMore, continueFrom }`.
+- Binary telecom media endpoints return `ArrayBuffer`.
+- `options.all` is only used on endpoints with safe paginated `data` plus `hasMore` behavior.
+
+### Known limits
+
+- Webhook verification helpers are not included yet. The public docs available in this repo workflow are not specific enough to safely implement the exact signature contract.
+- Some nested model fields are still intentionally broad where the upstream schema is weak or highly open-ended.
+- This package is an API SDK, not an application framework. Queueing, persistence, workflow orchestration, and webhook hosting should stay in the consuming app.
+- ServiceTitan may change upstream schemas over time. When that happens, the local OpenAPI JSON files should be updated first, then the SDK should be realigned to match.
+
+### Docs map
+
+- [`README.md`](./README.md): install, usage, examples, and package behavior
+- [`AGENTS.md`](./AGENTS.md): repo-specific engineering rules for Codex and contributors
+- [`docs/architecture.md`](./docs/architecture.md): structure, boundaries, and extension patterns
+
 ### Resources and quick examples
 
 Below is a brief tour of the main resource namespaces. Each list function supports `{ all?: boolean; pageSize?: number }` to fetch all pages server‑side.
@@ -165,10 +209,19 @@ const appts = await st.jpm.listAppointments({ scheduledOnOrAfter: "2025-01-01" }
 ```
 
 #### Marketing (`st.marketing`) and Marketing Ads (`st.marketingAds`)
-- Campaigns/Categories/Costs/Suppressions; Ads Attributions and Performance.
+- Campaigns/Categories/Costs; Ads Attributions, Performance, and Capacity Warnings.
 ```ts
 const campaigns = await st.marketing.listCampaigns({}, { all: true });
-const webLead = await st.marketingAds.createWebLeadFormAttribution({ webSessionData: {}, leadId: 42 });
+await st.marketingAds.createWebLeadFormAttribution({
+  leadId: 42,
+  webSessionData: {
+    landingPageUrl: "https://example.com/landing",
+    referrerUrl: "https://google.com",
+    utmSource: "google",
+    utmMedium: "cpc",
+    utmCampaign: "spring-promo",
+  },
+});
 ```
 
 #### Marketing Reputation (`st.marketingReputation`)
@@ -262,16 +315,18 @@ The package exports helper types from the root for stronger autocomplete and pay
 
 ```ts
 import type {
-  AccountingListParams,
+  CrmExportCustomer,
+  CreateEstimateRequest,
+  CreateWebLeadFormAttributionRequest,
   Contact,
   ContactMethodCreatePayload,
   CustomerInteractionsExportResponse,
-  EstimatePayload,
-  ExportParams,
   FindingCreatePayload,
   Invoice,
-  PaymentCreatePayload,
-  PricebookItemPayload,
+  JpmExportJob,
+  MarketingAdsPerformanceRecord,
+  SalesEstimatesExportResponse,
+  TelecomExportCall,
 } from "@masonlandcattle/servicetitan-sdk";
 ```
 
@@ -282,7 +337,7 @@ Many resource methods now use typed params and payload helpers directly, so edit
 ```ts
 import { ServiceTitanClient, CRM } from "@masonlandcattle/servicetitan-sdk";
 const st = new ServiceTitanClient({ /* creds */ });
-const customers = await CRM.listCustomers(st, { updatedAfter: "2024-01-01" }, { all: true });
+const customers = await CRM.listCustomers(st, { createdOnOrAfter: "2024-01-01" }, { all: true });
 ```
 
 ### Local development / testing without publishing
@@ -301,6 +356,9 @@ Run local example scripts directly against the source using `tsx`.
 npm run ex:crm
 npm run ex:dispatch
 npm run ex:equip
+npm run ex:namespaced
+npm run ex:crm-export
+npm run ex:telecom-media
 ```
 
 These scripts import from `../src`, so there's no need to publish/install.
@@ -311,6 +369,10 @@ These scripts import from `../src`, so there's no need to publish/install.
 
 Use `client.buildPath({ category, subject, idOrSubpath })` and `client.request(method, path, { params, data })`. To fetch every page server-side, pass `{ all: true, pageSize?: number }` to supported list functions.
 
+### Contributing / Codex
+
+If you are updating the SDK with Codex or another coding agent, read [`AGENTS.md`](./AGENTS.md) first. It captures the repo conventions used for the OpenAPI alignment work.
+
 ### Publish
 
 ```bash

package/dist/index.cjs

@@ -108,8 +108,9 @@ var ServiceTitanClient = class {
     });
     this.axiosInstance.interceptors.request.use((config) => {
       if (this.token) {
-        config.headers = config.headers || {};
-        config.headers["Authorization"] = `Bearer ${this.token}`;
+        const headers = config.headers ?? {};
+        headers.Authorization = `Bearer ${this.token}`;
+        config.headers = headers;
       }
       return config;
     });

package/dist/index.js

@@ -49,8 +49,9 @@ var ServiceTitanClient = class {
     });
     this.axiosInstance.interceptors.request.use((config) => {
       if (this.token) {
-        config.headers = config.headers || {};
-        config.headers["Authorization"] = `Bearer ${this.token}`;
+        const headers = config.headers ?? {};
+        headers.Authorization = `Bearer ${this.token}`;
+        config.headers = headers;
       }
       return config;
     });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@masonlandcattle/servicetitan-sdk",
   "author": "Mason Land & Cattle (https://github.com/MasonLandCattle)",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "ServiceTitan API SDK for Node.js and TypeScript with retries, rate limiting, pagination, and broad tenant API coverage.",
   "keywords": [
     "servicetitan",
@@ -43,7 +43,10 @@
     "ex:crm": "tsx examples/quick-crm.ts",
     "ex:dispatch": "tsx examples/quick-dispatch.ts",
     "ex:equip": "tsx examples/quick-equipment.ts",
-    "ex:jobs": "tsx examples/quick-jobs.ts"
+    "ex:jobs": "tsx examples/quick-jobs.ts",
+    "ex:namespaced": "tsx examples/namespaced-client.ts",
+    "ex:crm-export": "tsx examples/export-crm-customers.ts",
+    "ex:telecom-media": "tsx examples/telecom-media.ts"
   },
   "dependencies": {
     "axios": "^1.7.7",