@first-to-fly/crm-sdk 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -131,12 +131,31 @@ Messages include `{ source: 'crm-host', type, ... }`:
131
131
  ## Embedding the CRM in your SaaS
132
132
 
133
133
  Render the CRM as a cross-origin iframe in your app, authenticated **without cookies**
134
- and **without a reverse proxy**. You mint a short-lived signed assertion server-side,
135
- exchange it for a CRM bearer, and hand that bearer to the iframe over a secure
136
- `MessageChannel`. Two modules do the heavy lifting: `embed-server` (Node/Bun) and
137
- `embed-host` (browser).
134
+ and **without a reverse proxy**. Your server obtains a short-lived CRM bearer (via one
135
+ of the two auth options below) and hands it to the iframe over a secure `MessageChannel`.
136
+ Two modules do the heavy lifting: `embed-server` (Node/Bun) and `embed-host` (browser).
138
137
 
139
- ### How it works
138
+ ### Choosing a server auth approach
139
+
140
+ | | Option A — API-key | Option B — Signed assertion |
141
+ |---|---|---|
142
+ | **Setup** | CRM team gives you `app_id` + `app_secret` | You generate an RS256/ES256 keypair; CRM team registers your JWKS URL |
143
+ | **Shared secret** | `app_secret` on your server | None — private key stays on your server |
144
+ | **Peer dep** | None | `jose` (`npm i jose`) |
145
+ | **Helper** | `createEmbedSessionWithKey` | `createEmbedSession` (or `mintCrmAssertion` + `exchangeAssertion`) |
146
+
147
+ ### How it works (Option A — API-key)
148
+
149
+ ```
150
+ [your server] [browser] [CRM]
151
+ createEmbedSessionWithKey(user) ─exchange─▶ CRM bearer
152
+ │
153
+ createCrmEmbedHost({ iframe, getBearer })
154
+ │ ready → channel-init → ack
155
+ └──────── auth-tokens ─────────▶ CRM iframe loads
156
+ ```
157
+
158
+ ### How it works (Option B — Signed assertion)
140
159
 
141
160
  ```
142
161
  [your server] [browser] [CRM]
@@ -147,7 +166,57 @@ createEmbedSession(user) ─mint+exchange─▶ CRM bearer
147
166
  └──────── auth-tokens ─────────▶ CRM iframe loads
148
167
  ```
149
168
 
150
- ### One-time setup (with the CRM team)
169
+ ---
170
+
171
+ ### Option A: API-key auth (simpler, no keypair)
172
+
173
+ #### One-time setup
174
+
175
+ 1. Ask the CRM team to register your app. They give you an **`app_id`** and **`app_secret`**.
176
+ An admin in the CRM binds your app to a CRM workspace.
177
+ 2. Ask the CRM team for their **exchange base URL** and **embed origin**.
178
+
179
+ #### Server: exchange credentials for a bearer
180
+
181
+ ```typescript
182
+ import { createEmbedSessionWithKey } from '@first-to-fly/crm-sdk/embed-server';
183
+
184
+ // Endpoint your frontend calls to (re)obtain a CRM bearer:
185
+ app.post('/api/crm/session', async (req, res) => {
186
+ const user = req.user; // your authenticated user
187
+ const session = await createEmbedSessionWithKey(
188
+ {
189
+ appId: process.env.CRM_APP_ID!,
190
+ appSecret: process.env.CRM_APP_SECRET!,
191
+ user: {
192
+ id: user.id, // stable id in YOUR system
193
+ email: user.email,
194
+ role: 'member', // 'member' | 'admin'
195
+ name: user.name, // optional
196
+ avatar_url: user.avatar, // optional
197
+ },
198
+ },
199
+ { crmBaseUrl: process.env.CRM_BASE_URL! }, // e.g. https://api.crm.example.com
200
+ );
201
+ // { accessToken, expiresIn, workspaceId, user, role }
202
+ res.json(session);
203
+ });
204
+ ```
205
+
206
+ A rejected exchange throws `CrmExchangeError` with `.status` and `.code`
207
+ (e.g. `SUBAPP_DISABLED`, `IDENTITY_CONFLICT`).
208
+
209
+ ---
210
+
211
+ ### Option B: Signed-assertion auth (zero shared-secret)
212
+
213
+ > **Requires an assertion-capable CRM endpoint.** These helpers are retained for
214
+ > partners integrating against a CRM that still exposes the RS256/JWKS assertion
215
+ > exchange. The First-to-Fly hosted CRM now uses **Option A (API-key)** only, so
216
+ > use Option A there. Confirm with the CRM team which flow their deployment supports
217
+ > before choosing Option B.
218
+
219
+ #### One-time setup
151
220
 
152
221
  1. Generate an RS256 (or ES256) key pair. Keep the private key on your server.
153
222
  2. Serve your **public JWKS** at a public `https` URL (see `getCrmEmbedJwks` below).
@@ -155,7 +224,7 @@ createEmbedSession(user) ─mint+exchange─▶ CRM bearer
155
224
  app and enable it. An admin in the CRM binds your **`org_id`** to a CRM workspace.
156
225
  4. Ask the CRM team for their **exchange base URL** and **embed origin**.
157
226
 
158
- ### Server: mint + exchange
227
+ #### Server: mint + exchange
159
228
 
160
229
  ```typescript
161
230
  import { createEmbedSession, getCrmEmbedJwks } from '@first-to-fly/crm-sdk/embed-server';
@@ -195,7 +264,11 @@ Prefer to split minting and exchange? Use `mintCrmAssertion(input, config)` and
195
264
  `CrmExchangeError` with `.status` and `.code` (e.g. `IDENTITY_CONFLICT`,
196
265
  `WORKSPACE_NOT_OWNED`).
197
266
 
198
- ### Browser: host the iframe
267
+ Requires `jose` (peer dependency): `npm i jose`.
268
+
269
+ ---
270
+
271
+ ### Browser: host the iframe (same for both options)
199
272
 
200
273
  ```typescript
201
274
  import { createCrmEmbedHost, buildCrmEmbedUrl } from '@first-to-fly/crm-sdk/embed-host';
@@ -232,8 +305,122 @@ host.dispose();
232
305
  return a fresh bearer (call your `/session` endpoint again).
233
306
  - `crmOrigin` must exactly match the iframe's origin, and the CRM must allow your origin
234
307
  in its `frame-ancestors` (the CRM team configures this).
235
- - Assertions are single-use and live ≤120s — always mint fresh; never cache one.
236
- - `jose` is a peer dependency, required only by `embed-server`: `npm i jose`.
308
+ - Assertions (Option B) are single-use and live ≤120s — always mint fresh; never cache one.
309
+ - `jose` is only required for Option B (`embed-server` assertion path): `npm i jose`.
310
+
311
+ ## Calling CRM APIs from your backend
312
+
313
+ Once your server has a CRM bearer (from `createEmbedSessionWithKey`) — or an
314
+ `X-API-Key` for the public endpoints — use the typed REST client from
315
+ `@first-to-fly/crm-sdk/api` to call CRM resources directly. Every method returns
316
+ the **unwrapped** `data` (the `{ success, data }` envelope is stripped for you).
317
+
318
+ The typed resource methods (`contacts`, `leads`, …) hit `/api/*` routes that
319
+ require the **Bearer** token. An `apiKey` client should instead call `request()`
320
+ against the `/public/*` endpoints (see [Server-to-server](#server-to-server-with-an-api-key)).
321
+
322
+ **Errors** — every failure throws a `CrmApiError` (with `.status`, `.code`,
323
+ `.body`), so you can always `catch (e) { if (e instanceof CrmApiError) ... }`:
324
+
325
+ | Case | `status` | `code` |
326
+ |---|---|---|
327
+ | non-2xx response | the HTTP status | `error.code` / `error` string / `HTTP_<status>` |
328
+ | 2xx with `{ success: false }` (server mislabel) | the HTTP status (e.g. 200) | as above |
329
+ | network / DNS / connection failure | `0` | `NETWORK_ERROR` |
330
+ | request exceeded `timeoutMs` | `0` | `TIMEOUT` |
331
+
332
+ **Timeouts** — pass `timeoutMs` on the client (applies to all requests) and/or
333
+ per `request()` call; it's enforced with `AbortController`. If unset, requests
334
+ have no timeout.
335
+
336
+ ```typescript
337
+ const crm = createCrmApiClient({
338
+ crmBaseUrl: process.env.CRM_BASE_URL!,
339
+ accessToken: session.accessToken,
340
+ timeoutMs: 10_000, // 10s default for every request
341
+ });
342
+ ```
343
+
344
+ **Query arrays** — array query values serialize as repeated params
345
+ (`?tag=a&tag=b`). Note the CRM's `tags` filter on contacts/leads instead expects
346
+ a single **comma-separated string** (`?tags=a,b`), so pass that field as a joined
347
+ string, not an array.
348
+
349
+ The request/response types are **generated from the CRM's real zod route
350
+ contracts**, so they can't drift from the server (see "Regenerating types" below).
351
+
352
+ ```typescript
353
+ import { createCrmApiClient, CrmApiError } from '@first-to-fly/crm-sdk/api';
354
+ import { createEmbedSessionWithKey } from '@first-to-fly/crm-sdk/embed-server';
355
+
356
+ // 1) Get a bearer for the acting user (full API surface):
357
+ const session = await createEmbedSessionWithKey(
358
+ { appId, appSecret, user },
359
+ { crmBaseUrl: process.env.CRM_BASE_URL! },
360
+ );
361
+
362
+ const crm = createCrmApiClient({
363
+ crmBaseUrl: process.env.CRM_BASE_URL!, // e.g. https://api.crm.example.com
364
+ accessToken: session.accessToken, // → Authorization: Bearer <token>
365
+ });
366
+
367
+ // Typed contacts — args & return types come from the CRM zod contracts:
368
+ const { items, totalCount } = await crm.contacts.list({ page: 1, pageSize: 25, search: 'ada' });
369
+ const contact = await crm.contacts.create({ name: 'Ada Lovelace', email: 'ada@example.com' });
370
+
371
+ // Send a message in a conversation:
372
+ const message = await crm.conversations.messages.send(conversationId, {
373
+ message: 'Thanks for reaching out!',
374
+ });
375
+
376
+ // Generic escape hatch for any endpoint — still unwraps `data`:
377
+ const closeReasons = await crm.request<string[]>('GET', '/leads/close-reasons');
378
+
379
+ try {
380
+ await crm.contacts.get('does-not-exist');
381
+ } catch (err) {
382
+ if (err instanceof CrmApiError) {
383
+ console.error(err.status, err.code); // e.g. 404 "Contact not found"
384
+ }
385
+ }
386
+ ```
387
+
388
+ ### Server-to-server with an API key
389
+
390
+ For machine-to-machine calls you can pass an `X-API-Key` instead of a bearer:
391
+
392
+ ```typescript
393
+ const crm = createCrmApiClient({
394
+ crmBaseUrl: process.env.CRM_BASE_URL!,
395
+ apiKey: process.env.CRM_API_KEY!, // crm_live_... → X-API-Key
396
+ });
397
+
398
+ // API keys currently guard ONLY /api/public/* (create lead, batch leads, send email).
399
+ // Use request() for those routes:
400
+ await crm.request('POST', '/public/leads', { body: { name: 'Web lead', email: 'x@y.com' } });
401
+ ```
402
+
403
+ > Provide **exactly one** of `accessToken` or `apiKey` — passing neither or both
404
+ > throws. **Bearer** covers the full API surface; an **API key** today only covers
405
+ > `/api/public/*`, so the typed resource methods (contacts, leads, …) generally
406
+ > require a bearer.
407
+
408
+ ### Available resources
409
+
410
+ `contacts`, `leads`, `products` (`.list/.get/.create/.update/.delete`),
411
+ `tasks` (`.list/.create/.update`), `conversations`
412
+ (`.list/.get/.update` + `.messages.list/.send`), and `tags` (`.list/.create`) —
413
+ plus the generic `request<T>(method, path, { query?, body? })`.
414
+
415
+ ### Regenerating types
416
+
417
+ The contract types live in `src/generated/crm-contracts.ts` and are generated
418
+ from crm-be's zod schemas. After a CRM contract change, regenerate them from the
419
+ `crm-be` package:
420
+
421
+ ```bash
422
+ bun run gen:sdk-contracts
423
+ ```
237
424
 
238
425
  ## License
239
426
 
package/dist/api.cjs ADDED
@@ -0,0 +1,2 @@
1
+ "use strict";var v=Object.defineProperty;var Q=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var q=Object.prototype.hasOwnProperty;var I=(s,r)=>{for(var o in r)v(s,o,{get:r[o],enumerable:!0})},O=(s,r,o,i)=>{if(r&&typeof r=="object"||typeof r=="function")for(let a of $(r))!q.call(s,a)&&a!==o&&v(s,a,{get:()=>r[a],enumerable:!(i=Q(r,a))||i.enumerable});return s};var M=s=>O(v({},"__esModule",{value:!0}),s);var G={};I(G,{CrmApiError:()=>m,createCrmApiClient:()=>U,default:()=>x});module.exports=M(G);var m=class s extends Error{constructor(r,o,i,a,c){super(i),this.name="CrmApiError",this.status=r,this.code=o,this.body=a,c&&"cause"in c&&(this.cause=c.cause),Object.setPrototypeOf(this,s.prototype)}};function A(s){if(!s)return"";let r=new URLSearchParams;for(let[i,a]of Object.entries(s))if(a!=null)if(Array.isArray(a))for(let c of a)c!=null&&r.append(i,String(c));else r.append(i,String(a));let o=r.toString();return o?`?${o}`:""}function k(s){return typeof s=="object"&&s!==null&&"success"in s}function S(s,r){let o=k(s)&&s.success===!1?s:void 0,i=o?.error,a=typeof o?.message=="string"?o.message:void 0,c=i&&typeof i=="object"?i:void 0,f=typeof c?.code=="string"?c.code:void 0,C=typeof c?.message=="string"?c.message:void 0,t=typeof i=="string"?i:void 0,e=f??t??`HTTP_${r}`,n=C??a??t??`CRM request failed with status ${r}`;return{code:e,message:n}}function U(s){let{crmBaseUrl:r,accessToken:o,apiKey:i}=s;if(!o&&!i)throw new Error("createCrmApiClient: exactly one of `accessToken` or `apiKey` is required (got neither).");if(o&&i)throw new Error("createCrmApiClient: provide only one of `accessToken` or `apiKey` (got both).");let a=s.fetch??globalThis.fetch;if(typeof a!="function")throw new Error("createCrmApiClient: no fetch implementation available. Pass `fetch` explicitly.");let c=r.replace(/\/+$/,""),f=c.endsWith("/api")?c:`${c}/api`,C=o?{Authorization:`Bearer ${o}`}:{"X-API-Key":i};async function t(e,n,p={}){let w=`${f}${n}${A(p.query)}`,h={...C},L=p.body!==void 0;L&&(h["Content-Type"]="application/json");let y=p.timeoutMs??s.timeoutMs,T=y!==void 0?new AbortController:void 0,b=!1,P;T&&y!==void 0&&(P=setTimeout(()=>{b=!0,T.abort()},y));let l;try{l=await a(w,{method:e,headers:h,body:L?JSON.stringify(p.body):void 0,signal:T?.signal})}catch(u){if(b||u instanceof Error&&u.name==="AbortError")throw new m(0,"TIMEOUT",`CRM request timed out after ${y}ms`,u,{cause:u});let E=u instanceof Error?u.message:"CRM request failed (network error)";throw new m(0,"NETWORK_ERROR",E,u,{cause:u})}finally{P!==void 0&&clearTimeout(P)}let g=await l.text(),d=g;if(g)try{d=JSON.parse(g)}catch{d=g}let R=k(d)&&d.success===!1;if(!l.ok||R){let{code:u,message:E}=S(d,l.status);throw new m(l.status,u,E,d)}if(k(d)&&d.success===!0)return d.data;if(g!=="")return d}return{contacts:{list:e=>t("GET","/contacts",{query:e}),get:e=>t("GET",`/contacts/${encodeURIComponent(e)}`),create:e=>t("POST","/contacts",{body:e}),update:(e,n)=>t("PUT",`/contacts/${encodeURIComponent(e)}`,{body:n}),delete:e=>t("DELETE",`/contacts/${encodeURIComponent(e)}`)},leads:{list:e=>t("GET","/leads",{query:e}),get:e=>t("GET",`/leads/${encodeURIComponent(e)}`),create:e=>t("POST","/leads",{body:e}),update:(e,n)=>t("PUT",`/leads/${encodeURIComponent(e)}`,{body:n}),delete:e=>t("DELETE",`/leads/${encodeURIComponent(e)}`)},tasks:{list:e=>t("GET","/tasks",{query:e}),create:(e,n)=>t("POST",`/leads/${encodeURIComponent(e)}/tasks`,{body:n}),update:(e,n,p)=>t("PATCH",`/leads/${encodeURIComponent(e)}/tasks/${encodeURIComponent(n)}`,{body:p})},products:{list:e=>t("GET","/products",{query:e}),get:e=>t("GET",`/products/${encodeURIComponent(e)}`),create:e=>t("POST","/products",{body:e}),update:(e,n)=>t("PUT",`/products/${encodeURIComponent(e)}`,{body:n}),delete:e=>t("DELETE",`/products/${encodeURIComponent(e)}`)},conversations:{list:e=>t("GET","/conversations",{query:e}),get:e=>t("GET",`/conversations/${encodeURIComponent(e)}`),update:(e,n)=>t("PUT",`/conversations/${encodeURIComponent(e)}`,{body:n}),messages:{list:(e,n)=>t("GET",`/conversations/${encodeURIComponent(e)}/messages`,{query:n}),send:(e,n)=>t("POST",`/conversations/${encodeURIComponent(e)}/messages`,{body:n})}},tags:{list:e=>t("GET","/tags",{query:e}),create:e=>t("POST","/tags",{body:e})},request:t}}var x=U;0&&(module.exports={CrmApiError,createCrmApiClient});
2
+ //# sourceMappingURL=api.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/api.ts"],"sourcesContent":["/**\n * Typed CRM REST API client for SaaS backends.\n *\n * Construct with `createCrmApiClient({ crmBaseUrl, accessToken | apiKey })` and\n * call typed resource methods (contacts, leads, conversations, messages, tasks,\n * products, tags) or the generic `request<T>()` escape hatch. Every method\n * returns the UNWRAPPED `data` from the CRM's `{ success, data }` envelope.\n *\n * Auth:\n * - `accessToken` (from `createEmbedSessionWithKey().data.access_token`) is\n * sent as `Authorization: Bearer <token>` and covers the full API surface.\n * The typed resource methods below hit `/api/*` routes that require this\n * **Bearer** token.\n * - `apiKey` (`crm_live_...`) is sent as `X-API-Key` and today only guards\n * `/api/public/*`. An `apiKey` client should use the generic `request()`\n * against those `/public/*` endpoints, NOT the typed resource methods.\n *\n * Error handling — every failure is thrown as a {@link CrmApiError} so callers\n * can `catch (e) { if (e instanceof CrmApiError) ... }`:\n * - non-2xx responses, AND 2xx responses the server mislabels with an\n * `{ success: false }` envelope, throw with the HTTP `status` and a code\n * derived from the body.\n * - network / DNS / connection failures throw with `status: 0` and\n * `code: 'NETWORK_ERROR'`.\n * - a request that exceeds `timeoutMs` (via `AbortController`) throws with\n * `status: 0` and `code: 'TIMEOUT'`.\n *\n * Timeouts — pass `timeoutMs` on the client (default for all requests) and/or\n * per request. If unset there is no timeout.\n *\n * @packageDocumentation\n */\n\nimport type {\n Contact,\n ContactCreate,\n ContactUpdate,\n ContactQuery,\n ContactList,\n Lead,\n LeadCreate,\n LeadUpdate,\n LeadQuery,\n Task,\n TaskCreate,\n TaskUpdate,\n TaskQuery,\n Conversation,\n ConversationQuery,\n ConversationUpdate,\n Message,\n MessageQuery,\n MessageCreate,\n Product,\n ProductCreate,\n ProductUpdate,\n ProductQuery,\n Tag,\n TagCreate,\n TagQuery,\n TagWithUsage,\n ListEnvelope,\n} from './generated/crm-contracts';\n\nexport type * from './generated/crm-contracts';\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\ntype FetchLike = typeof fetch;\n\n/** Options for {@link createCrmApiClient}. Exactly one of accessToken / apiKey. */\nexport interface CrmApiClientOptions {\n /** Base URL of the CRM, e.g. `https://crm.example.com` (no trailing `/api`). */\n crmBaseUrl: string;\n /** Bearer token from `createEmbedSessionWithKey` — full API surface. */\n accessToken?: string;\n /** Server-to-server API key (`crm_live_...`) — `/api/public/*` only today. */\n apiKey?: string;\n /** Custom fetch implementation (e.g. for Node < 18 or testing). */\n fetch?: FetchLike;\n /**\n * Default per-request timeout in milliseconds, enforced via `AbortController`.\n * On timeout the request throws a {@link CrmApiError} (`status: 0`,\n * `code: 'TIMEOUT'`). If unset (default), requests have no timeout.\n */\n timeoutMs?: number;\n}\n\n/** CRM success envelope. */\ninterface SuccessEnvelope<T> {\n success: true;\n data: T;\n message?: string;\n meta?: Record<string, unknown>;\n}\n\n/** CRM error envelope. */\ninterface ErrorEnvelope {\n success: false;\n error: string;\n message?: string;\n details?: string;\n}\n\ntype QueryPrimitive = string | number | boolean;\ntype QueryValue =\n | QueryPrimitive\n | Array<QueryPrimitive>\n | undefined\n | null;\ntype QueryParams = Record<string, QueryValue>;\n\ninterface RequestOptions {\n query?: QueryParams;\n body?: unknown;\n /**\n * Per-request timeout in milliseconds (overrides the client `timeoutMs`).\n * On timeout the request throws a {@link CrmApiError} (`status: 0`,\n * `code: 'TIMEOUT'`).\n */\n timeoutMs?: number;\n}\n\n/**\n * Error thrown for any failed CRM request:\n * - a non-2xx HTTP response,\n * - a 2xx response carrying an `{ success: false }` envelope (server mislabel),\n * - a network/DNS/connection failure (`status: 0`, `code: 'NETWORK_ERROR'`),\n * - a timeout / abort (`status: 0`, `code: 'TIMEOUT'`).\n */\nexport class CrmApiError extends Error {\n /** HTTP status code (0 for network errors / timeouts). */\n readonly status: number;\n /**\n * Machine-readable code. For envelope errors: the object `error.code`, else\n * the string `error`, else `HTTP_<status>`. For transport failures:\n * `NETWORK_ERROR` or `TIMEOUT`.\n */\n readonly code: string;\n /** Parsed response body, or the underlying error for transport failures. */\n readonly body: unknown;\n\n constructor(\n status: number,\n code: string,\n message: string,\n body: unknown,\n options?: { cause?: unknown },\n ) {\n super(message);\n this.name = 'CrmApiError';\n this.status = status;\n this.code = code;\n this.body = body;\n // Preserve the underlying error (network/abort) without requiring the\n // ES2022 `cause` constructor option.\n if (options && 'cause' in options) {\n (this as { cause?: unknown }).cause = options.cause;\n }\n Object.setPrototypeOf(this, CrmApiError.prototype);\n }\n}\n\n/** The client returned by {@link createCrmApiClient}. */\nexport interface CrmApiClient {\n contacts: {\n list(query?: ContactQuery): Promise<ContactList>;\n get(id: string): Promise<Contact>;\n create(body: ContactCreate): Promise<Contact>;\n update(id: string, body: ContactUpdate): Promise<Contact>;\n delete(id: string): Promise<void>;\n };\n leads: {\n list(query?: LeadQuery): Promise<ListEnvelope<Lead>>;\n get(id: string): Promise<Lead>;\n create(body: LeadCreate): Promise<Lead>;\n update(id: string, body: LeadUpdate): Promise<Lead>;\n delete(id: string): Promise<void>;\n };\n tasks: {\n list(query?: TaskQuery): Promise<ListEnvelope<Task>>;\n create(leadId: string, body: TaskCreate): Promise<Task>;\n update(leadId: string, taskId: string, body: TaskUpdate): Promise<Task>;\n };\n products: {\n list(query?: ProductQuery): Promise<ListEnvelope<Product>>;\n get(id: string): Promise<Product>;\n create(body: ProductCreate): Promise<Product>;\n update(id: string, body: ProductUpdate): Promise<Product>;\n delete(id: string): Promise<void>;\n };\n conversations: {\n list(query?: ConversationQuery): Promise<ListEnvelope<Conversation>>;\n get(id: string): Promise<Conversation>;\n update(id: string, body: ConversationUpdate): Promise<Conversation>;\n messages: {\n list(\n conversationId: string,\n query?: MessageQuery,\n ): Promise<ListEnvelope<Message>>;\n send(conversationId: string, body: MessageCreate): Promise<Message>;\n };\n };\n tags: {\n list(query?: TagQuery): Promise<ListEnvelope<TagWithUsage>>;\n create(body: TagCreate): Promise<Tag>;\n };\n /** Generic escape hatch — returns the unwrapped `data` typed as `T`. */\n request<T>(\n method: string,\n path: string,\n options?: RequestOptions,\n ): Promise<T>;\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Serialize query params. Array values are appended as repeated params\n * (`?tag=a&tag=b`); `undefined`/`null` values (and array elements) are skipped.\n *\n * NOTE on the CRM's `tags` filter: the CRM's contacts/leads query schemas expect\n * `tags` as a single comma-separated string (`?tags=a,b`), which the server\n * splits on `,`. If you pass `tags` as an array here it becomes repeated params\n * (`?tags=a&tags=b`), which those endpoints will NOT parse as multiple tags —\n * pass a comma-joined string for that specific field. All other core query\n * fields are primitives. No core query field is a nested object.\n */\nfunction serializeQuery(query?: QueryParams): string {\n if (!query) return '';\n const params = new URLSearchParams();\n for (const [key, value] of Object.entries(query)) {\n if (value === undefined || value === null) continue;\n if (Array.isArray(value)) {\n for (const el of value) {\n if (el === undefined || el === null) continue;\n params.append(key, String(el));\n }\n } else {\n params.append(key, String(value));\n }\n }\n const qs = params.toString();\n return qs ? `?${qs}` : '';\n}\n\nfunction isEnvelope(v: unknown): v is SuccessEnvelope<unknown> | ErrorEnvelope {\n return typeof v === 'object' && v !== null && 'success' in v;\n}\n\n/** Derive `{ code, message }` from a parsed CRM error envelope + HTTP status. */\nfunction deriveError(parsed: unknown, status: number): { code: string; message: string } {\n const envelope =\n isEnvelope(parsed) && parsed.success === false\n ? (parsed as ErrorEnvelope & { error?: unknown })\n : undefined;\n const rawError: unknown = envelope?.error;\n const envMessage =\n typeof envelope?.message === 'string' ? envelope.message : undefined;\n\n // error can be a string (\"human string\" or a code) OR an object { code, message }.\n const errorObj =\n rawError && typeof rawError === 'object'\n ? (rawError as { code?: unknown; message?: unknown })\n : undefined;\n const errorObjCode =\n typeof errorObj?.code === 'string' ? errorObj.code : undefined;\n const errorObjMessage =\n typeof errorObj?.message === 'string' ? errorObj.message : undefined;\n const errorStr = typeof rawError === 'string' ? rawError : undefined;\n\n const code = errorObjCode ?? errorStr ?? `HTTP_${status}`;\n const message =\n errorObjMessage ??\n envMessage ??\n errorStr ??\n `CRM request failed with status ${status}`;\n\n return { code, message };\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\nexport function createCrmApiClient(opts: CrmApiClientOptions): CrmApiClient {\n const { crmBaseUrl, accessToken, apiKey } = opts;\n\n if (!accessToken && !apiKey) {\n throw new Error(\n 'createCrmApiClient: exactly one of `accessToken` or `apiKey` is required (got neither).',\n );\n }\n if (accessToken && apiKey) {\n throw new Error(\n 'createCrmApiClient: provide only one of `accessToken` or `apiKey` (got both).',\n );\n }\n\n const fetchImpl: FetchLike = opts.fetch ?? globalThis.fetch;\n if (typeof fetchImpl !== 'function') {\n throw new Error(\n 'createCrmApiClient: no fetch implementation available. Pass `fetch` explicitly.',\n );\n }\n\n // Normalize base: strip trailing slash, then ensure it ends with `/api`.\n const trimmed = crmBaseUrl.replace(/\\/+$/, '');\n const apiBase = trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;\n\n const authHeaders: Record<string, string> = accessToken\n ? { Authorization: `Bearer ${accessToken}` }\n : { 'X-API-Key': apiKey as string };\n\n async function request<T>(\n method: string,\n path: string,\n options: RequestOptions = {},\n ): Promise<T> {\n const url = `${apiBase}${path}${serializeQuery(options.query)}`;\n const headers: Record<string, string> = { ...authHeaders };\n const hasBody = options.body !== undefined;\n if (hasBody) headers['Content-Type'] = 'application/json';\n\n const timeoutMs = options.timeoutMs ?? opts.timeoutMs;\n const controller =\n timeoutMs !== undefined ? new AbortController() : undefined;\n let timedOut = false;\n let timer: ReturnType<typeof setTimeout> | undefined;\n if (controller && timeoutMs !== undefined) {\n timer = setTimeout(() => {\n timedOut = true;\n controller.abort();\n }, timeoutMs);\n }\n\n let res: Response;\n try {\n res = await fetchImpl(url, {\n method,\n headers,\n body: hasBody ? JSON.stringify(options.body) : undefined,\n signal: controller?.signal,\n });\n } catch (err) {\n // Network error, DNS failure, connection refused, or abort/timeout.\n if (\n timedOut ||\n (err instanceof Error && err.name === 'AbortError')\n ) {\n throw new CrmApiError(\n 0,\n 'TIMEOUT',\n `CRM request timed out after ${timeoutMs}ms`,\n err,\n { cause: err },\n );\n }\n const message =\n err instanceof Error ? err.message : 'CRM request failed (network error)';\n throw new CrmApiError(0, 'NETWORK_ERROR', message, err, { cause: err });\n } finally {\n if (timer !== undefined) clearTimeout(timer);\n }\n\n // Parse body (JSON when possible, else raw text).\n const text = await res.text();\n let parsed: unknown = text;\n if (text) {\n try {\n parsed = JSON.parse(text);\n } catch {\n parsed = text;\n }\n }\n\n // Treat an `{ success: false }` envelope as an error regardless of HTTP\n // status — a server can mislabel an error as 2xx.\n const isEnvelopeError = isEnvelope(parsed) && parsed.success === false;\n if (!res.ok || isEnvelopeError) {\n const { code, message } = deriveError(parsed, res.status);\n throw new CrmApiError(res.status, code, message, parsed);\n }\n\n // Unwrap `{ success, data }`.\n if (isEnvelope(parsed) && parsed.success === true) {\n return parsed.data as T;\n }\n\n // Empty 2xx body (e.g. 204 / empty DELETE) → undefined, not \"\".\n if (text === '') {\n return undefined as T;\n }\n\n // Non-enveloped 2xx response — return the raw parsed body.\n return parsed as T;\n }\n\n return {\n contacts: {\n list: (query) => request<ContactList>('GET', '/contacts', { query: query as QueryParams }),\n get: (id) => request<Contact>('GET', `/contacts/${encodeURIComponent(id)}`),\n create: (body) => request<Contact>('POST', '/contacts', { body }),\n update: (id, body) => request<Contact>('PUT', `/contacts/${encodeURIComponent(id)}`, { body }),\n delete: (id) => request<void>('DELETE', `/contacts/${encodeURIComponent(id)}`),\n },\n leads: {\n list: (query) => request<ListEnvelope<Lead>>('GET', '/leads', { query: query as QueryParams }),\n get: (id) => request<Lead>('GET', `/leads/${encodeURIComponent(id)}`),\n create: (body) => request<Lead>('POST', '/leads', { body }),\n update: (id, body) => request<Lead>('PUT', `/leads/${encodeURIComponent(id)}`, { body }),\n delete: (id) => request<void>('DELETE', `/leads/${encodeURIComponent(id)}`),\n },\n tasks: {\n list: (query) => request<ListEnvelope<Task>>('GET', '/tasks', { query: query as QueryParams }),\n create: (leadId, body) =>\n request<Task>('POST', `/leads/${encodeURIComponent(leadId)}/tasks`, { body }),\n update: (leadId, taskId, body) =>\n request<Task>(\n 'PATCH',\n `/leads/${encodeURIComponent(leadId)}/tasks/${encodeURIComponent(taskId)}`,\n { body },\n ),\n },\n products: {\n list: (query) => request<ListEnvelope<Product>>('GET', '/products', { query: query as QueryParams }),\n get: (id) => request<Product>('GET', `/products/${encodeURIComponent(id)}`),\n create: (body) => request<Product>('POST', '/products', { body }),\n update: (id, body) => request<Product>('PUT', `/products/${encodeURIComponent(id)}`, { body }),\n delete: (id) => request<void>('DELETE', `/products/${encodeURIComponent(id)}`),\n },\n conversations: {\n list: (query) =>\n request<ListEnvelope<Conversation>>('GET', '/conversations', { query: query as QueryParams }),\n get: (id) => request<Conversation>('GET', `/conversations/${encodeURIComponent(id)}`),\n update: (id, body) =>\n request<Conversation>('PUT', `/conversations/${encodeURIComponent(id)}`, { body }),\n messages: {\n list: (conversationId, query) =>\n request<ListEnvelope<Message>>(\n 'GET',\n `/conversations/${encodeURIComponent(conversationId)}/messages`,\n { query: query as QueryParams },\n ),\n send: (conversationId, body) =>\n request<Message>(\n 'POST',\n `/conversations/${encodeURIComponent(conversationId)}/messages`,\n { body },\n ),\n },\n },\n tags: {\n list: (query) => request<ListEnvelope<TagWithUsage>>('GET', '/tags', { query: query as QueryParams }),\n create: (body) => request<Tag>('POST', '/tags', { body }),\n },\n request,\n };\n}\n\nexport default createCrmApiClient;\n"],"mappings":"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","names":["api_exports","__export","CrmApiError","createCrmApiClient","api_default","__toCommonJS","_CrmApiError","status","code","message","body","options","serializeQuery","query","params","key","value","el","qs","isEnvelope","v","deriveError","parsed","envelope","rawError","envMessage","errorObj","errorObjCode","errorObjMessage","errorStr","opts","crmBaseUrl","accessToken","apiKey","fetchImpl","trimmed","apiBase","authHeaders","request","method","path","url","headers","hasBody","timeoutMs","controller","timedOut","timer","res","err","text","isEnvelopeError","id","leadId","taskId","conversationId"]}