@vennyx/solicrm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vennyx A.Ş.
+
+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,137 @@
+# @vennyx/solicrm
+
+Official TypeScript SDK for the [SoliCRM](https://solicrm.com) API — typed access to
+contacts, companies, deals, pipelines, activities, tasks, notes, saved views and
+cross-resource search.
+
+Every request/response type is derived from the **same zod schemas the server uses**, so
+the SDK cannot drift from the API. Types are bundled into this package; you do not need
+any additional `@types/*`.
+
+## Install
+
+```sh
+npm install @vennyx/solicrm
+# or
+bun add @vennyx/solicrm
+```
+
+Requires Node.js ≥ 18 (or Bun). ESM only — this package has no CommonJS build.
+
+### TypeScript setup
+
+The bundled `dist/index.d.ts` is self-contained, but it references the standard `fetch`
+globals (`Response`, `RequestInit`, `AbortSignal`), so your `tsconfig.json` needs either
+`"types": ["node"]` or `"lib": [..., "DOM"]`. Both `moduleResolution: "nodenext"` and
+`"bundler"` are verified to resolve this package with zero errors.
+
+## Quick start
+
+```ts
+import { SolicrmClient } from '@vennyx/solicrm'
+
+const solicrm = new SolicrmClient({
+  apiKey: process.env.SOLICRM_API_KEY!, // "scrm_..." — created in the SoliCRM dashboard
+  tenantId: process.env.SOLICRM_TENANT_ID!, // the tenant the key belongs to
+  // baseUrl: 'https://api.solicrm.com'   // default
+})
+
+const page = await solicrm.contacts.list({
+  limit: 25,
+  sort: { field: 'created_at', direction: 'desc' }, // keys come from FIELD_CATALOG
+  filters: { status: 'active' },
+})
+for (const contact of page.items) {
+  console.log(contact.id, contact.firstName, contact.lastName, contact.status)
+}
+
+const created = await solicrm.contacts.create({
+  firstName: 'Ada',
+  lastName: 'Lovelace',
+  status: 'lead',
+})
+await solicrm.contacts.update(created.id, { jobTitle: 'Analyst' })
+```
+
+### Resources
+
+`contacts`, `companies`, `deals`, `pipelines`, `activities`, `tasks`, `notes`, `views`
+(saved views) and `search` (cross-resource). Escape hatch for anything not modelled yet:
+`solicrm.http.requestJson(method, path, schema, options)` / `solicrm.http.requestVoid(...)`.
+
+## Keyset pagination
+
+List endpoints are cursor based (`items` / `hasMore` / `nextCursor`). Each resource has a
+`listAll()` generator that walks every page, and the underlying `paginateAll` helper is
+exported for custom endpoints. Both **fail loudly** instead of silently truncating when the
+server reports `hasMore: true` with a `null` cursor, or repeats a cursor:
+
+```ts
+for await (const deal of solicrm.deals.listAll({ limit: 100 })) {
+  console.log(deal.id, deal.amount) // amount is a string — see "Money and dates"
+}
+```
+
+```ts
+import { paginateAll } from '@vennyx/solicrm'
+
+for await (const item of paginateAll((q) => solicrm.contacts.list(q), { limit: 100 })) {
+  console.log(item.id)
+}
+```
+
+## Errors
+
+| Class | Meaning |
+| --- | --- |
+| `SolicrmError` | Client-side misuse (missing `apiKey`, unknown sort field, aborted request) |
+| `SolicrmApiError` | Server returned a non-2xx status — `.status`, `.message`, `.body` |
+| `SolicrmResponseError` | Server returned 2xx but the body did not match the contract schema |
+
+`SolicrmApiError.message` carries the server's message **verbatim, in Turkish** (SoliCRM's
+API speaks Turkish to end users). `.body` is the raw parsed body, so richer envelopes
+survive intact — the plan-limit response of `contacts.create`, for example, is
+`{ code, limit, planCode }` with **no** `error` field at all:
+
+```ts
+import { readContactLimitReached, SolicrmApiError } from '@vennyx/solicrm'
+
+try {
+  await solicrm.contacts.create({ firstName: 'Grace', lastName: 'Hopper', status: 'lead' })
+} catch (error) {
+  if (error instanceof SolicrmApiError && error.status === 402) {
+    const limit = readContactLimitReached(error.body)
+    console.log(limit?.code, limit?.limit, limit?.planCode)
+  }
+}
+```
+
+## Money and dates
+
+Money fields (`amount`, `annualRevenue`) are `numeric(18,2)` columns and the API returns
+them as **strings**; timestamps are ISO 8601 **strings**. The SDK passes both through
+untouched and performs no arithmetic — it never calls `parseFloat`/`Number`. Pick your own
+decimal and date libraries (SoliCRM itself uses `bignumber.js` and `luxon`).
+
+## Custom `fetch` and retries
+
+```ts
+const solicrm = new SolicrmClient({
+  apiKey,
+  tenantId,
+  fetch: myInstrumentedFetch,
+  retry: { maxAttempts: 3 },
+})
+```
+
+Retries use exponential backoff with half jitter and only apply to retryable statuses.
+`Authorization` cannot be overridden through `headers`.
+
+## Related
+
+- [`@vennyx/solicrm-mcp`](https://www.npmjs.com/package/@vennyx/solicrm-mcp) — MCP server
+  that exposes the same operations as tools for AI agents.
+
+## License
+
+MIT © Vennyx A.Ş.