@cosmoops/connect-sdk 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.19.0
+
+### Added
+
+- **`connect.contacts`** - who a workspace already knows how to reach.
+
+  ```ts
+  const contact = await connect.contacts.lookupByPhone({ workspaceId, phone });
+  if (contact) {
+    // A caller this workspace has met before.
+  }
+  ```
+
+  `lookupByPhone` is one point read, cheap enough for a screen pop on every
+  inbound call, and resolves to `null` for a first-time caller - the ordinary
+  case, not an error. `get(contactId, { workspaceId })` reads the record behind
+  an id you already hold. Needs a key scoped to `contacts:read` and a live
+  subscription in the workspace.
+
+  **This is the telephony identity, not a CRM record.** A contact is keyed by
+  `primaryPhone` - the one fact every inbound call carries - and it is written
+  automatically: a voice agent creates one on the first call from a new number
+  and fills fields in as it learns them. `source` tells you which kind you are
+  holding (`call` means an agent guessed and nobody has confirmed), and
+  `phones[].verified` tells you the same about a single value.
+
+  **Reference it, do not copy it.** If your application keeps its own customer
+  records, store this contact's `id` on yours. Two writable copies of a
+  person's name with no single owner drift, and Connect's is the one an agent
+  keeps updating from calls. Storing the id also makes `Booking.contactId` an
+  **exact** join - so "which of my records is this appointment for" is a lookup
+  rather than a phone-number match, including for appointments a voice agent
+  booked where nobody ever chose one of your records.
+
+  Read-only, deliberately. Writing into a store with a per-field provenance
+  chain means declaring where your facts came from and how they merge with a
+  human's; nothing needs that yet.
+
+- New exported types: `ConnectContact`, `ContactChannelValue`, `ContactSource`,
+  and `ContactsResource` / `LookupContactInput` from
+  `@cosmoops/connect-sdk/server`.
+
 ## 0.18.0
 
 ### Added

package/README.md

@@ -342,6 +342,7 @@ try {
 | `entitlements` | `getReadiness` · `getSubscription` · `hasFeature` |
 | `billing` | `listPlans` · `getAddonUsage` · `consumeAddon` |
 | `drive` | `upload` · `getFileUrl` · `getPreviewUrl` |
+| `contacts` | `lookupByPhone` · `get` |
 | `scheduling` | `listEventTypes` · `findSlots` · `listBookings` · `createBooking` · `rescheduleBooking` · `cancelBooking` |
 | `ai` | `chat` · `extract` |
 | `otp` | `send` · `verify` |

package/dist/cjs/server/client.js

@@ -7,6 +7,7 @@ const ai_js_1 = require("./resources/ai.js");
 const data_js_1 = require("./resources/data.js");
 const workspaces_js_1 = require("./resources/workspaces.js");
 const scheduling_js_1 = require("./resources/scheduling.js");
+const contacts_js_1 = require("./resources/contacts.js");
 const kv_js_1 = require("./resources/kv.js");
 const billing_js_1 = require("./resources/billing.js");
 const drive_js_1 = require("./resources/drive.js");
@@ -82,6 +83,8 @@ class ConnectClient {
     drive;
     /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
     scheduling;
+    /** Who a workspace already knows how to reach, by phone or by id. */
+    contacts;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -131,6 +134,7 @@ class ConnectClient {
         this.billing = new billing_js_1.BillingResource(transport);
         this.drive = new drive_js_1.DriveResource(transport);
         this.scheduling = new scheduling_js_1.SchedulingResource(transport);
+        this.contacts = new contacts_js_1.ContactsResource(transport);
         this.ai = new ai_js_1.AiResource(transport);
         this.data = new data_js_1.DataResource(transport);
         this.kv = new kv_js_1.KvResource(transport);
@@ -146,4 +150,4 @@ class ConnectClient {
 }
 exports.ConnectClient = ConnectClient;
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-exports.SDK_VERSION = "0.18.0";
+exports.SDK_VERSION = "0.19.0";

package/dist/cjs/server/resources/contacts.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContactsResource = void 0;
+const http_js_1 = require("../http.js");
+const acting_as_js_1 = require("./acting-as.js");
+/**
+ * Who a workspace already knows how to reach.
+ *
+ * **This is the telephony identity, not a CRM record.** A contact is keyed by
+ * `primaryPhone` - the one fact every inbound call carries - and it is written
+ * automatically: a voice agent creates one on the first call from a new number
+ * and fills fields in as it learns them. `source` says which kind you are
+ * holding, and it is worth rendering: `call` means an agent guessed and nobody
+ * has confirmed, `manual` means a person typed it.
+ *
+ * **Reference it, do not copy it.** If your application keeps its own customer
+ * records, store this contact's `id` on yours rather than duplicating the
+ * fields. Two writable copies of a person's name with no single owner drift,
+ * and Connect's is the one an agent keeps updating from calls. The id is also
+ * an exact join to anything else keyed by it - `Booking.contactId`, most
+ * usefully - so "which of my records is this appointment for" becomes a lookup
+ * instead of a phone match.
+ *
+ * Read-only for now. Writing into a store with a per-field provenance chain
+ * means declaring where your facts came from and how they merge with a
+ * human's, and nothing needs that yet.
+ */
+class ContactsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * "Do we already know this number?" - one point read, cheap enough for a
+     * screen pop on every inbound call.
+     *
+     * Resolves to `null` for a number nobody has called from before. That is the
+     * ordinary case for a first-time caller, not an error, which is why it is a
+     * null rather than a thrown `ConnectError`.
+     */
+    async lookupByPhone(input) {
+        const result = await (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: "/contacts",
+            query: { workspaceId: input.workspaceId, phone: input.phone },
+            headers: (0, acting_as_js_1.actingAs)(input.asUser),
+        });
+        return result.contact ?? null;
+    }
+    /**
+     * The record behind an id you already hold.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another workspace - deliberately the same answer,
+     * since telling those apart would confirm a contact exists somewhere else.
+     */
+    get(contactId, options) {
+        return (0, http_js_1.request)(this.transport, {
+            method: "GET",
+            path: `/contacts/${encodeURIComponent(contactId)}`,
+            query: { workspaceId: options.workspaceId },
+            headers: (0, acting_as_js_1.actingAs)(options.asUser),
+        });
+    }
+}
+exports.ContactsResource = ContactsResource;

package/dist/esm/server/client.js

@@ -4,6 +4,7 @@ import { AiResource } from "./resources/ai.js";
 import { DataResource, storePassthrough } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 import { SchedulingResource } from "./resources/scheduling.js";
+import { ContactsResource } from "./resources/contacts.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -79,6 +80,8 @@ export class ConnectClient {
     drive;
     /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
     scheduling;
+    /** Who a workspace already knows how to reach, by phone or by id. */
+    contacts;
     /** RAG chat and structured extraction. */
     ai;
     /** Your application's own document store - see `DataResource`. */
@@ -128,6 +131,7 @@ export class ConnectClient {
         this.billing = new BillingResource(transport);
         this.drive = new DriveResource(transport);
         this.scheduling = new SchedulingResource(transport);
+        this.contacts = new ContactsResource(transport);
         this.ai = new AiResource(transport);
         this.data = new DataResource(transport);
         this.kv = new KvResource(transport);
@@ -142,4 +146,4 @@ export class ConnectClient {
     }
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export const SDK_VERSION = "0.18.0";
+export const SDK_VERSION = "0.19.0";

package/dist/esm/server/resources/contacts.js

@@ -0,0 +1,62 @@
+import { request } from "../http.js";
+import { actingAs } from "./acting-as.js";
+/**
+ * Who a workspace already knows how to reach.
+ *
+ * **This is the telephony identity, not a CRM record.** A contact is keyed by
+ * `primaryPhone` - the one fact every inbound call carries - and it is written
+ * automatically: a voice agent creates one on the first call from a new number
+ * and fills fields in as it learns them. `source` says which kind you are
+ * holding, and it is worth rendering: `call` means an agent guessed and nobody
+ * has confirmed, `manual` means a person typed it.
+ *
+ * **Reference it, do not copy it.** If your application keeps its own customer
+ * records, store this contact's `id` on yours rather than duplicating the
+ * fields. Two writable copies of a person's name with no single owner drift,
+ * and Connect's is the one an agent keeps updating from calls. The id is also
+ * an exact join to anything else keyed by it - `Booking.contactId`, most
+ * usefully - so "which of my records is this appointment for" becomes a lookup
+ * instead of a phone match.
+ *
+ * Read-only for now. Writing into a store with a per-field provenance chain
+ * means declaring where your facts came from and how they merge with a
+ * human's, and nothing needs that yet.
+ */
+export class ContactsResource {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * "Do we already know this number?" - one point read, cheap enough for a
+     * screen pop on every inbound call.
+     *
+     * Resolves to `null` for a number nobody has called from before. That is the
+     * ordinary case for a first-time caller, not an error, which is why it is a
+     * null rather than a thrown `ConnectError`.
+     */
+    async lookupByPhone(input) {
+        const result = await request(this.transport, {
+            method: "GET",
+            path: "/contacts",
+            query: { workspaceId: input.workspaceId, phone: input.phone },
+            headers: actingAs(input.asUser),
+        });
+        return result.contact ?? null;
+    }
+    /**
+     * The record behind an id you already hold.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another workspace - deliberately the same answer,
+     * since telling those apart would confirm a contact exists somewhere else.
+     */
+    get(contactId, options) {
+        return request(this.transport, {
+            method: "GET",
+            path: `/contacts/${encodeURIComponent(contactId)}`,
+            query: { workspaceId: options.workspaceId },
+            headers: actingAs(options.asUser),
+        });
+    }
+}

package/dist/types/server/client.d.ts

@@ -5,6 +5,7 @@ import { AiResource } from "./resources/ai.js";
 import { DataResource } from "./resources/data.js";
 import { WorkspacesResource } from "./resources/workspaces.js";
 import { SchedulingResource } from "./resources/scheduling.js";
+import { ContactsResource } from "./resources/contacts.js";
 import { KvResource } from "./resources/kv.js";
 import { BillingResource } from "./resources/billing.js";
 import { DriveResource } from "./resources/drive.js";
@@ -78,6 +79,8 @@ export declare class ConnectClient {
     readonly drive: DriveResource;
     /** A subscribing workspace's own calendar - what is bookable, free, and booked. */
     readonly scheduling: SchedulingResource;
+    /** Who a workspace already knows how to reach, by phone or by id. */
+    readonly contacts: ContactsResource;
     /** RAG chat and structured extraction. */
     readonly ai: AiResource;
     /** Your application's own document store - see `DataResource`. */
@@ -112,4 +115,4 @@ export declare class ConnectClient {
     constructor(options: ConnectClientOptions);
 }
 /** Kept in step with `package.json` by `sdk.test.ts`. */
-export declare const SDK_VERSION = "0.18.0";
+export declare const SDK_VERSION = "0.19.0";

package/dist/types/server/index.d.ts

@@ -28,6 +28,7 @@ export type { SessionsResource } from "./resources/sessions.js";
 export type { ExecuteIntegrationActionInput, IntegrationsResource } from "./resources/integrations.js";
 export type { PlatformResource } from "./resources/platform.js";
 export type { SchedulingResource, FindSlotsInput, ListBookingsInput, CreateBookingInput, RescheduleBookingInput, } from "./resources/scheduling.js";
+export type { ContactsResource, LookupContactInput } from "./resources/contacts.js";
 /**
  * Webhook verification and a ready-made POST route. Server-only for the
  * obvious reason: the signing secret must never reach a browser bundle.

package/dist/types/server/resources/contacts.d.ts

@@ -0,0 +1,60 @@
+import { type TransportOptions } from "../http.js";
+import type { ConnectContact } from "../../types.js";
+export interface LookupContactInput {
+    workspaceId: string;
+    /**
+     * Any reasonable spelling. `+919000000001`, `919000000001` and
+     * `+91 90000 00001` all resolve to the same contact - the number is
+     * normalized to E.164 before the lookup, because comparing unnormalized is
+     * how a contact that exists reads as absent.
+     */
+    phone: string;
+    /** See `ActingAsOption` on the scheduling resource - same contract. */
+    asUser?: string;
+}
+/**
+ * Who a workspace already knows how to reach.
+ *
+ * **This is the telephony identity, not a CRM record.** A contact is keyed by
+ * `primaryPhone` - the one fact every inbound call carries - and it is written
+ * automatically: a voice agent creates one on the first call from a new number
+ * and fills fields in as it learns them. `source` says which kind you are
+ * holding, and it is worth rendering: `call` means an agent guessed and nobody
+ * has confirmed, `manual` means a person typed it.
+ *
+ * **Reference it, do not copy it.** If your application keeps its own customer
+ * records, store this contact's `id` on yours rather than duplicating the
+ * fields. Two writable copies of a person's name with no single owner drift,
+ * and Connect's is the one an agent keeps updating from calls. The id is also
+ * an exact join to anything else keyed by it - `Booking.contactId`, most
+ * usefully - so "which of my records is this appointment for" becomes a lookup
+ * instead of a phone match.
+ *
+ * Read-only for now. Writing into a store with a per-field provenance chain
+ * means declaring where your facts came from and how they merge with a
+ * human's, and nothing needs that yet.
+ */
+export declare class ContactsResource {
+    private readonly transport;
+    constructor(transport: TransportOptions);
+    /**
+     * "Do we already know this number?" - one point read, cheap enough for a
+     * screen pop on every inbound call.
+     *
+     * Resolves to `null` for a number nobody has called from before. That is the
+     * ordinary case for a first-time caller, not an error, which is why it is a
+     * null rather than a thrown `ConnectError`.
+     */
+    lookupByPhone(input: LookupContactInput): Promise<ConnectContact | null>;
+    /**
+     * The record behind an id you already hold.
+     *
+     * Throws `ConnectError` with `code: "not_found"` for an id that does not
+     * exist *or* belongs to another workspace - deliberately the same answer,
+     * since telling those apart would confirm a contact exists somewhere else.
+     */
+    get(contactId: string, options: {
+        workspaceId: string;
+        asUser?: string;
+    }): Promise<ConnectContact>;
+}

package/dist/types/types.d.ts

@@ -1224,3 +1224,48 @@ export interface ListBookingsPage {
     hasMore: boolean;
     totalCount: number;
 }
+/**
+ * A phone or email on a contact.
+ *
+ * `verified` means a human confirmed it reaches them - only a manual source
+ * may ever set it. Branch on it: an unverified value is one an extraction
+ * heard on a call and nobody has checked since.
+ */
+export interface ContactChannelValue {
+    value: string;
+    label: string | null;
+    verified: boolean;
+}
+/**
+ * How a contact came to exist. `call` means a voice agent created it from an
+ * inbound call; `manual` and `import` are the two a human stands behind.
+ */
+export type ContactSource = "call" | "manual" | "import" | "api" | "extraction";
+/**
+ * Someone a workspace knows how to reach - **the telephony identity**, not a
+ * CRM record. See `ContactsResource` for why the difference decides whether
+ * you reference this or copy it.
+ */
+export interface ConnectContact {
+    id: string;
+    /** E.164, and immutable - the key this contact is identified by. */
+    primaryPhone: string;
+    phones: ContactChannelValue[];
+    emails: ContactChannelValue[];
+    name: {
+        display: string | null;
+        given: string | null;
+        family: string | null;
+    };
+    business: {
+        company: string | null;
+        role: string | null;
+        gstin: string | null;
+        website: string | null;
+        address: string | null;
+    };
+    tags: string[];
+    source: ContactSource;
+    createdAt: string;
+    updatedAt: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmoops/connect-sdk",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Official server-side SDK for the CosmoOps Connect platform API - Login with Connect, entitlements, billing and metering.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",