@delofarag/crm-utils 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# `@delofarag/crm-utils`
+
+TypeScript-Hilfsbibliothek für **CRM-Integrationen**: ein gemeinsames Datenmodell für Tokens (`TokenStore`), eine abstrakte **CRM-API** (Contacts, Companies, Notes, Search) und pro Anbieter eine **OAuth-Verbindung** plus HTTP-Wrapper.
+
+**Aktuell implementiert:** HubSpot (`Hubspot`, `HubspotConnection`).
+
+---
+
+## Für KI / Cursor — Kurzüberblick
+
+| Frage | Antwort |
+|--------|---------|
+| Wie instanziiere ich den CRM-Client? | `getCRM("hubspot", { clientId, redirectUri })` → `Hubspot` |
+| Wo ist OAuth? | `hub.connection` (`HubspotConnection`): `buildAuthorizeUrl` → User zu HubSpot → Callback mit `code` → `exchangeAuthorizationCode(clientSecret, { code })` |
+| Wo sind CRM-Daten-APIs? | `hub.getContacts`, `hub.getCompanies`, `hub.createContact`, … — immer mit `accessToken` (serverseitig) |
+| Darf `clientSecret` ins Frontend? | **Nein.** Nur Server (Route Handler, Backend). |
+| Tokens speichern? | `TokenStore` ist das beabsichtigte Shape; Persistenz (DB) passiert **in deiner App** nach den Connection-Returns. |
+| Neues CRM hinzufügen? | `CRM` + `CrmConnection` erweitern, `getCRM` + `CRMInitMap` / `CRMInstanceMap` in `getCRM.ts` ergänzen, `CRMs`-Array erweitern. |
+
+---
+
+## Installation
+
+```bash
+pnpm add @delofarag/crm-utils
+# oder npm / yarn
+```
+
+Paket baut nach `dist/` (`pnpm build` im Package). Consumer importieren aus dem Package-Root (`@delofarag/crm-utils`).
+
+**Peer-Umgebung:** Node mit `fetch` (Node 18+) oder entsprechende Polyfills. `oauth-helpers` nutzt `node:crypto` für `randomState` — für reine Browser-Nutzung der OAuth-Helfer ggf. eigenes State erzeugen.
+
+---
+
+## Architektur
+
+```
+getCRM(name, init)
+    └── Hubspot
+            ├── connection: HubspotConnection  ← OAuth (authorize, code exchange, refresh, metadata)
+            └── CRM-Methoden                 ← REST (Contacts, Companies, Notes, Search)
+```
+
+- **`CRM` (abstrakt):** gemeinsame Methodensignatur für alle CRMs (`getContacts`, `getCompanies`, `createContact`, `updateContact`, `createNote`, `searchRecords`).
+- **`CrmConnection` (abstrakt):** OAuth-Schicht; `HubspotConnection` setzt HubSpot-URLs und Token-Flow um.
+- **`TokenStore`:** flaches Objekt für OAuth-State und Tokens (`access_token`, `refresh_token`, `token_expires_at`, `provider_account_id`, `id` für eure User-DB, …).
+
+---
+
+## Öffentliche Exports (`src/index.ts`)
+
+| Export | Rolle |
+|--------|--------|
+| `getCRM`, `CRMs`, `CRMName`, `CRMInitMap`, `CRMInstanceMap` | Factory und Typen für unterstützte CRMs |
+| `CRM` | Abstrakte Basisklasse für CRM-Implementierungen |
+| `CrmConnection` | Abstrakte Basisklasse für OAuth (`provider`) |
+| `TokenStore` | Token-/State-Shape |
+| `Hubspot`, `HubspotConnection` | HubSpot-Implementierung |
+| `HubspotInit` | `{ clientId, redirectUri }` |
+| HubSpot-Zod-Typen | `HubspotTokenResponse`, Schemas (Parsing von Token-JSON) |
+| `oauth-helpers` | `randomState`, `buildQueryString`, `postFormUrlEncoded`, `toExpiresAt` |
+
+---
+
+## HubSpot: Initialisierung
+
+```ts
+import { getCRM } from "@delofarag/crm-utils"
+
+const hub = getCRM("hubspot", {
+    clientId: process.env.HUBSPOT_CLIENT_ID!,
+    redirectUri: "https://your-domain.com/api/hubspot/callback",
+})
+```
+
+- **`redirectUri`:** muss **exakt** mit einer in der HubSpot-App eingetragenen Redirect-URL übereinstimmen und bei `buildAuthorizeUrl` und `exchangeAuthorizationCode` identisch sein (OAuth). Das ist die URL, auf die HubSpot den Browser mit `code` und `state` zurückschickt.
+- **`clientId`:** öffentlich; **`clientSecret`** wird **nicht** im Constructor gespeichert, sondern nur an `exchangeAuthorizationCode` und `refreshAccessToken` / `getValidAccessToken` übergeben.
+
+---
+
+## HubSpot: OAuth-Ablauf (Reihenfolge)
+
+1. **`hub.connection.buildAuthorizeUrl({ scopes, supabase_id? })`**
+   - Erzeugt `state` (CSRF) und ein `tokenStore`-Objekt mit `state` (und optional `id` aus `supabase_id`).
+   - Rückgabe: `{ authorizeUrl, state, tokenStore }` — Browser des Users zu `authorizeUrl` navigieren (volle Seiten-Navigation, kein `fetch` für den Start). State/Tokens bei dir persistieren, wenn du willst (nach dem Return).
+
+2. **Callback-Route** (Query: `code`, `state`):
+   - `state` mit gespeichertem State abgleichen (Session/DB/Cookie).
+   - **`hub.connection.exchangeAuthorizationCode(clientSecret, { code, id? })`**
+   - Liefert u. a. `tokenStore` (inkl. `access_token`, `refresh_token`, `provider_account_id` / Portal-ID aus Metadata) und `raw` (HubSpot-Antwort).
+
+3. **Später / bei abgelaufenem Access Token:**
+   - **`hub.connection.refreshAccessToken(clientSecret, { refreshToken })`**
+   - oder **`hub.connection.getValidAccessToken(clientSecret, { accessToken, expiresAt, refreshToken, skewMs? })`** — refresht bei Bedarf automatisch.
+
+4. **Optional:** **`hub.connection.fetchAccessTokenMetadata(accessToken)`** — u. a. `hub_id` (Portal).
+
+**Nicht** für den Refresh: `redirectUri` (nur Authorize + Code-Exchange).
+
+---
+
+## HubSpot: CRM-API (Datenebene)
+
+Alle folgenden Methoden erwarten ein gültiges **`accessToken`** (serverseitig). Rückgaben sind bewusst **`Promise<unknown>`** — Response-Shapes kommen von HubSpot; bei Bedarf in der App casten oder validieren.
+
+| Methode | Kurzbeschreibung |
+|---------|------------------|
+| `getContacts({ accessToken, limit?, after? })` | Liste Contacts (Pagination `after`) |
+| `getCompanies({ accessToken, limit?, after? })` | Liste Companies |
+| `createContact({ accessToken, properties })` | Neuer Contact |
+| `updateContact({ accessToken, id, properties })` | Contact PATCH |
+| `createNote({ accessToken, body, associateToObjectType, associateToId })` | Note + Association zu Contact/Company/Deal |
+| `searchRecords({ accessToken, objectType, filterGroups?, properties?, limit?, after? })` | CRM Search API |
+
+HubSpot-HTTP-Basis: `https://api.hubapi.com`; Fehler werden als `Error` mit Status-Text geworfen.
+
+---
+
+## `TokenStore`
+
+`TokenStore` (`src/types.ts`) bündelt u. a.:
+
+- **`state`** — OAuth CSRF (vor dem Callback).
+- **`id`** — eure interne User-/Tenant-ID (z. B. Supabase), z. B. über `buildAuthorizeUrl({ supabase_id })` oder `exchangeAuthorizationCode` `{ id }`.
+- **`provider_account_id`** — z. B. HubSpot Portal-ID (String).
+- **`access_token` / `refresh_token` / `token_expires_at` / `token_last_refreshed_at`**
+
+Persistenz (Datenbank, Session) implementierst **du** in der App, sobald du `tokenStore` aus den Methoden zurückbekommst — **crm-utils** bleibt ohne DB.
+
+---
+
+## Neues CRM ergänzen (Checkliste)
+
+1. Ordner `src/crms/<name>/` mit Implementierung.
+2. Klasse erweitert `CRM` (alle abstrakten Methoden implementieren).
+3. Connection-Klasse erweitert `CrmConnection` mit `provider` und OAuth-Logik.
+4. **`getCRM.ts`:** `CRMs` um Namen erweitern, `CRMInitMap` / `CRMInstanceMap` und `switch` in `getCRM` ergänzen.
+5. **`src/index.ts`:** neue Typen/Klassen exportieren.
+6. README / Changelog im Repo pflegen.
+
+---
+
+## Sicherheit — Kurz
+
+- **`clientSecret`**, **Refresh/Access Tokens** nur auf dem Server halten.
+- **`redirectUri`** in der OAuth-App registrieren; keine Wildcards nachlässig mischen.
+- **`state`** immer prüfen, bevor `code` getauscht wird.
+- Öffentliche Repos: keine echten Tokens committen.
+
+---
+

package/dist/BaseCrm.d.ts

@@ -0,0 +1,37 @@
+export default abstract class BaseCrm {
+    abstract readonly provider: string;
+    abstract getContacts(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    abstract getCompanies(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    abstract createContact(options: {
+        accessToken: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    abstract updateContact(options: {
+        accessToken: string;
+        id: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    abstract createNote(options: {
+        accessToken: string;
+        body: string;
+        associateToObjectType: string;
+        associateToId: string;
+    }): Promise<unknown>;
+    abstract searchRecords(options: {
+        accessToken: string;
+        objectType: string;
+        filterGroups?: unknown[];
+        properties?: string[];
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+}
+//# sourceMappingURL=BaseCrm.d.ts.map

package/dist/BaseCrm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseCrm.d.ts","sourceRoot":"","sources":["../src/BaseCrm.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,OAAO;IACjC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAElC,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE;QAC1B,WAAW,EAAE,MAAM,CAAA;QACnB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE;QAC3B,WAAW,EAAE,MAAM,CAAA;QACnB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC5B,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAA;KAC/D,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC5B,WAAW,EAAE,MAAM,CAAA;QACnB,EAAE,EAAE,MAAM,CAAA;QACV,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAA;KAC/D,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE;QACzB,WAAW,EAAE,MAAM,CAAA;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,qBAAqB,EAAE,MAAM,CAAA;QAC7B,aAAa,EAAE,MAAM,CAAA;KACxB,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC5B,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;QACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;QACrB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACjB,GAAG,OAAO,CAAC,OAAO,CAAC;CACvB"}

package/dist/BaseCrm.js

@@ -0,0 +1,3 @@
+export default class BaseCrm {
+}
+//# sourceMappingURL=BaseCrm.js.map

package/dist/BaseCrm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseCrm.js","sourceRoot":"","sources":["../src/BaseCrm.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAgB,OAAO;CAyCpC"}

package/dist/CRM.d.ts

@@ -0,0 +1,37 @@
+export default abstract class CRM {
+    abstract readonly provider: string;
+    abstract getContacts(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    abstract getCompanies(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    abstract createContact(options: {
+        accessToken: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    abstract updateContact(options: {
+        accessToken: string;
+        id: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    abstract createNote(options: {
+        accessToken: string;
+        body: string;
+        associateToObjectType: string;
+        associateToId: string;
+    }): Promise<unknown>;
+    abstract searchRecords(options: {
+        accessToken: string;
+        objectType: string;
+        filterGroups?: unknown[];
+        properties?: string[];
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+}
+//# sourceMappingURL=CRM.d.ts.map

package/dist/CRM.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CRM.d.ts","sourceRoot":"","sources":["../src/CRM.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,GAAG;IAChC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAElC,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE;QAC7B,WAAW,EAAE,MAAM,CAAA;QACnB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE;QAC9B,WAAW,EAAE,MAAM,CAAA;QACnB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC/B,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAA;KAC5D,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC/B,WAAW,EAAE,MAAM,CAAA;QACnB,EAAE,EAAE,MAAM,CAAA;QACV,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAA;KAC5D,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,UAAU,CAAC,OAAO,EAAE;QAC5B,WAAW,EAAE,MAAM,CAAA;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,qBAAqB,EAAE,MAAM,CAAA;QAC7B,aAAa,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,OAAO,CAAC;IAEpB,QAAQ,CAAC,aAAa,CAAC,OAAO,EAAE;QAC/B,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,CAAC,EAAE,OAAO,EAAE,CAAA;QACxB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;QACrB,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAA;KACd,GAAG,OAAO,CAAC,OAAO,CAAC;CACpB"}

package/dist/CRM.js

@@ -0,0 +1,3 @@
+export default class CRM {
+}
+//# sourceMappingURL=CRM.js.map

package/dist/CRM.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CRM.js","sourceRoot":"","sources":["../src/CRM.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAgB,GAAG;CAyChC"}

package/dist/CrmConnection.d.ts

@@ -0,0 +1,4 @@
+export default abstract class CrmConnection {
+    abstract readonly provider: string;
+}
+//# sourceMappingURL=CrmConnection.d.ts.map

package/dist/CrmConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrmConnection.d.ts","sourceRoot":"","sources":["../src/CrmConnection.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,aAAa;IACvC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CACrC"}

package/dist/CrmConnection.js

@@ -0,0 +1,3 @@
+export default class CrmConnection {
+}
+//# sourceMappingURL=CrmConnection.js.map

package/dist/CrmConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CrmConnection.js","sourceRoot":"","sources":["../src/CrmConnection.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,OAAO,OAAgB,aAAa;CAE1C"}

package/dist/crms/hubspot/hubspot.d.ts

@@ -0,0 +1,183 @@
+import CRM from "../../CRM";
+import CrmConnection from "../../CrmConnection";
+import { HubspotInit } from "./types";
+import type { HubspotAccessTokenMetadata, HubspotTokenResponse } from "./types";
+import type { TokenStore } from "../../types";
+export declare class HubspotConnection extends CrmConnection {
+    readonly provider: "hubspot";
+    private clientId;
+    private redirectUri;
+    constructor(args: HubspotInit);
+    /**
+     * OAuth-Start: Authorize-URL + state.
+     *
+      * frontend && server
+     */
+    buildAuthUrl(args: {
+        scopes: string[];
+        supabase_id?: string;
+    }): Promise<{
+        authorizeUrl: string;
+        tokenStore: TokenStore;
+        state: string;
+    } | {
+        authorizeUrl: string;
+        state: string;
+        tokenStore?: undefined;
+    }>;
+    /**
+     * Callback: code → Tokens.
+     *
+      * server-only
+     */
+    codeToTokens(clientSecret: string, args: {
+        code: string;
+        supabase_id?: string;
+    }): Promise<{
+        raw: {
+            access_token: string;
+            refresh_token?: string | undefined;
+            expires_in?: number | undefined;
+            token_type?: string | undefined;
+        };
+        tokenStore: TokenStore;
+        portalId: number | undefined;
+    } | {
+        raw: {
+            access_token: string;
+            refresh_token?: string | undefined;
+            expires_in?: number | undefined;
+            token_type?: string | undefined;
+        };
+        portalId: number | undefined;
+        tokenStore?: undefined;
+    }>;
+    /**
+     * Refresh: refresh_token → new access_token.
+     *
+      * server-only
+     */
+    refreshAccessToken(clientSecret: string, args: {
+        refreshToken: string;
+    }): Promise<{
+        raw: HubspotTokenResponse;
+        tokenStore: TokenStore;
+    }>;
+    /**
+     * HubSpot: GET /oauth/v1/access-tokens/{token} — u.a. hub_id (Portal).
+     *
+      * frontend && server
+     */
+    fetchAccessTokenMetadata(accessToken: string): Promise<HubspotAccessTokenMetadata>;
+    /**
+     * Hilfe: gültigen Access Token — entweder aus tokenStore oder nach Refresh.
+     *
+      * server-only
+     */
+    getValidAccessToken(clientSecret: string, args: {
+        accessToken?: string | undefined;
+        expiresAt?: Date | string | null;
+        refreshToken?: string | null;
+        skewMs?: number;
+    }): Promise<string>;
+}
+export declare class Hubspot extends CRM {
+    readonly provider: "hubspot";
+    connection: HubspotConnection;
+    constructor({ clientId, redirectUri }: HubspotInit);
+    /**
+     * Holt eine Seite von HubSpot Contacts.
+     *
+     * - `limit`: wie viele Contacts du pro Request willst (Pagination Page Size)
+     * - `after`: Cursor für die nächste Seite (kommt typischerweise aus `paging.next.after`)
+     *
+     * Typical use: UI-Liste anzeigen oder initial Candidates laden.
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    getContacts(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    /**
+     * Holt eine Seite von HubSpot Companies.
+     *
+     * - `limit`: wie viele Companies pro Request
+     * - `after`: Cursor für die nächste Seite
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    getCompanies(options: {
+        accessToken: string;
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+    /**
+     * Erstellt einen neuen Contact.
+     *
+     * `properties` sind HubSpot-Property-Namen → Values. Beispiel: `{ email: \"a@b.com\", firstname: \"Max\" }`.
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    createContact(options: {
+        accessToken: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    /**
+     * Updated einen bestehenden Contact (PATCH).
+     *
+     * - `id`: HubSpot Contact ID
+     * - `properties`: Partial Update (nur die Felder, die du ändern willst)
+     *
+     * Typical use: nach AI-Screening `status`, `ai_score`, `ai_summary` etc. zurückschreiben.
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    updateContact(options: {
+        accessToken: string;
+        id: string;
+        properties: Record<string, string | number | boolean | null>;
+    }): Promise<unknown>;
+    /**
+     * Erstellt eine Note (Timeline/History Eintrag) und hängt sie an ein Objekt (Contact/Company/Deal).
+     *
+     * Notes sind super, um Ergebnisse „auditierbar“ abzulegen (was hat die AI gemacht / was kam beim Call raus),
+     * ohne dass du zig neue Custom Properties brauchst.
+     *
+     * - `body`: Text/HTML Inhalt der Note (HubSpot Property: `hs_note_body`)
+     * - `associateToObjectType`: z.B. `contact`, `company`, `deal`
+     * - `associateToId`: ID des Ziel-Objekts in HubSpot
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    createNote(options: {
+        accessToken: string;
+        body: string;
+        associateToObjectType: string;
+        associateToId: string;
+    }): Promise<unknown>;
+    /**
+     * Generische Suche über HubSpot-Objekte (contacts/companies/deals/custom objects).
+     *
+     * Im Gegensatz zu `getContacts()` (nur Listen) kannst du hier **Filter** angeben.
+     *
+     * - `objectType`: z.B. `contacts`, `companies`, `deals`
+     * - `filterGroups`: HubSpot Search-Filter (Raw-Shape; du gibst das HubSpot-Format direkt rein)
+     * - `properties`: welche Properties du zurückhaben willst
+     * - `limit`/`after`: Pagination
+     *
+     * Typical use: „gib mir alle Kandidaten mit status = X“ ohne alles zu laden.
+     *
+     * server-only (weil `accessToken` ein Secret ist)
+     */
+    searchRecords(options: {
+        accessToken: string;
+        objectType: string;
+        filterGroups?: unknown[];
+        properties?: string[];
+        limit?: number;
+        after?: string;
+    }): Promise<unknown>;
+}
+//# sourceMappingURL=hubspot.d.ts.map

package/dist/crms/hubspot/hubspot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hubspot.d.ts","sourceRoot":"","sources":["../../../src/crms/hubspot/hubspot.ts"],"names":[],"mappings":"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"}