@masonlandcattle/servicetitan-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MasonLandCattle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+## ServiceTitan SDK (Node.js / TypeScript)
+
+A pragmatic ServiceTitan API client with:
+
+- Robust auth (Client Credentials)
+- **Retries** with exponential backoff + jitter
+- Honors **Retry-After**, handles 429/5xx
+- **Rate limiting** with Bottleneck (concurrency + minTime)
+- URL builder and **pagination** helpers (`getAll`)
+- Modular resources (Jobs, Appointments, Materials, Accounting/Invoices)
+
+### Install
+
+```bash
+npm install @masonlandcattle/servicetitan-sdk
+```
+
+### Configure
+
+Set env vars or pass options:
+
+- `TENANT_ID`
+- `APP_KEY`
+- `CLIENT_ID`
+- `SECRET_KEY`
+- Optional: `ENVIRONMENT` = `production` | `development`
+
+### Usage
+
+```ts
+import { ServiceTitanClient, Jobs, Materials, Accounting } from "@masonlandcattle/servicetitan-sdk";
+
+const st = new ServiceTitanClient({
+  tenantId: process.env.TENANT_ID,
+  appKey: process.env.APP_KEY,
+  clientId: process.env.CLIENT_ID,
+  clientSecret: process.env.SECRET_KEY,
+  environment: (process.env.ENVIRONMENT as any) || "production",
+  retries: 3,
+  maxConcurrent: 5,
+  minTimeMs: 100,
+});
+
+const jobs = await Jobs.listJobs(st, { page: 1, pageSize: 100 });
+await Jobs.createJobNote(st, 123456, "Hello from SDK", true);
+
+const mats = await Materials.listMaterials(st, { page: 1, pageSize: 200 });
+await Materials.createMaterial(st, { name: "Widget", code: "W-1" });
+
+const allInvoices = await Accounting.getAllInvoices(st, { customerId: 42 }, 500);
+```
+
+### Local development / testing without publishing
+
+Run local example scripts directly against the source using `tsx`.
+
+1. Set environment variables:
+   - `TENANT_ID`
+   - `APP_KEY`
+   - `CLIENT_ID`
+   - `SECRET_KEY`
+
+2. Execute examples:
+
+```bash
+npm run ex:crm
+npm run ex:dispatch
+npm run ex:equip
+```
+
+These scripts import from `../src`, so there's no need to publish/install.
+
+### API Shape
+
+`/{category}/v2/tenant/{TENANT_ID}/{subject}`
+
+Use `client.buildPath({ category, subject, idOrSubpath })` and `client.request(method, path, { params, data })`.
+
+### Publish
+
+```bash
+npm run build
+npm publish --access public
+```
+
+> Not affiliated with ServiceTitan. Respect rate limits and terms.