@chatlychat/sdk-js 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @chatlychat/sdk-js — changelog
+
+## Unreleased
+
+- `subscribe` now reports INBOUND typing through `handlers.onTyping` — the
+  send half (`setTyping`) shipped first and there was no way to show the
+  visitor that the agent was typing. Push-only, like `setTyping`: typing is a
+  socket event with no HTTP route, so a polling subscription warns once rather
+  than never firing in silence.
+- `onTyping` is edge-triggered and self-clearing (`TYPING_STOP_AFTER_MS`,
+  3.5s — the widget's own window), because `typing.stop` is best-effort and an
+  agent who closes their laptop mid-sentence never sends one.
+- `identify()` now remembers the contact id it was given, so `setTyping` names
+  the right contact on a returning browser instead of `'unknown'`.
+
+## 0.1.0 — 2026-05-25
+
+- Initial public release.
+- `Chatly` class: `identify`, `track`, `open`, `close`, `toggle`, `send`, `on`,
+  `destroy`.
+- TypeScript types ship with the package; no `@types/*` package needed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chatly Engineering
+
+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

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @chatlychat/sdk-js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser SDK for the Chatly platform: control the in-page widget, identify
+visitors, fire CDP events, and — headlessly — list conversations, send
+messages and subscribe to replies without rendering our UI at all.
+
+> **Not published to npm yet.** The install line below will 404 today. The
+> widget-control half of this surface is already available with no package:
+> load the widget snippet and call the methods on `window.Chatly`. The
+> headless half (`listConversations`, `listMessages`, `send`, `uploadFile`,
+> `subscribe`, `rate`, `emailTranscript`) has **no** global and needs this
+> package or a direct call to the documented REST endpoints.
+
+```bash
+npm install @chatlychat/sdk-js
+# or
+pnpm add @chatlychat/sdk-js
+```
+
+## Quick start
+
+```ts
+import { Chatly } from '@chatlychat/sdk-js';
+
+// The constructor is PRIVATE. `init` is the only way in.
+const chatly = Chatly.init({ publicId: 'ch_web_0192…' });
+
+await chatly.identify({ externalId: 'user_42', name: 'Ada', userHash: '…' });
+const { conversationId } = await chatly.startConversation('Hello');
+await chatly.send(conversationId, 'and one more thing');
+```
+
+## `Chatly.init(options)`
+
+| Option        | Type      | Default                      | Notes                                                                     |
+| ------------- | --------- | ---------------------------- | ------------------------------------------------------------------------- |
+| `publicId`    | `string`  | —                            | The web channel's public id, from Dashboard → Channels.                   |
+| `apiUrl`      | `string?` | `https://api.chatlychat.com` | Set only if you self-host.                                                |
+| `realtimeUrl` | `string?` | reported by the server       | Socket.IO host for `subscribe()`. Only for a host the server cannot know. |
+
+## Methods
+
+Widget control — these mirror `window.Chatly` and need the widget on the page:
+
+- `open()` / `close()`
+
+Visitor identity and analytics:
+
+- `identify(input)` → `{ contactId }`. Pass `userHash` to make the identity
+  **verified**; without it the visitor is unverified and tools that require a
+  proven identity will refuse.
+- `track(name, properties?)`
+
+Headless conversation surface — no widget required:
+
+- `startConversation(body, attachments?)` → `{ conversationId }`
+- `send(conversationId, body, attachments?)`
+- `listConversations(limit = 20)`
+- `listMessages(conversationId, limit = 50)`
+- `subscribe(conversationId, handlers, options?)` → `Subscription`. Uses the
+  push socket when it can and falls back to polling, so it keeps working
+  where a WebSocket cannot be opened.
+- `uploadFile(file)` → `VisitorAttachment`, to pass to `send` or
+  `startConversation`
+- `rate(conversationId, score, comment?)`
+- `emailTranscript(conversationId, email)`
+
+## Signed page context
+
+`setContext` is **not** on this SDK — it is on the widget's own global. See
+the [web channel guide](https://chatlychat.com/guides/channel-web) for the
+call and [identity verification](https://chatlychat.com/docs/identity-verification)
+for how to mint the signed `contextToken`.
+
+## This README used to document an API that did not exist
+
+For the record, because it may have been copied: it described
+`new Chatly({ channelPublicId, baseUrl, widgetSelector, locale })`, plus
+`toggle()`, `on()`, `destroy()` and `send(body)`. **None of those exist.** The
+constructor is private, the option names are `publicId` / `apiUrl` /
+`realtimeUrl`, and `send` takes a conversation id first. Corrected
+2026-10-12 against `src/index.ts`.

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Browser SDK. Pairs with the widget loader to give product code a way to
+ * identify visitors, fire CDP events, and control the widget.
+ *
+ *   import { Chatly } from '@chatlychat/sdk-js';
+ *   const lc = Chatly.init({ publicId: 'acme-web', apiUrl: 'https://api.acme.com' });
+ *   await lc.identify({ email: 'a@b.com', name: 'Alice' });
+ *   await lc.track('signup_completed', { plan: 'pro' });
+ *   lc.open();
+ */
+import type { HeadlessConversation, HeadlessMessage, SubscribeHandlers, SubscribeOptions, Subscription } from './types.js';
+export type { HeadlessConversation, HeadlessMessage, SubscribeHandlers, SubscribeOptions, SocketIoFactory, Subscription, TypingSignal, } from './types.js';
+export { TYPING_STOP_AFTER_MS } from './live.js';
+export interface SdkOptions {
+    publicId: string;
+    apiUrl?: string;
+    /**
+     * Socket.IO host, for the push path of `subscribe()`.
+     *
+     * Normally unnecessary: `/v1/widget/init` reports the right one and the SDK
+     * remembers it. Set this only for a deployment whose realtime host the
+     * server cannot know — the same escape hatch the widget's embed has.
+     */
+    realtimeUrl?: string;
+}
+export interface IdentifyInput {
+    /**
+     * Your own id for this person. Optional — see `identify` — but it is the
+     * only field identity verification can bind, so a channel with verification
+     * enabled needs this plus `userHash` to consider the visitor proven.
+     */
+    externalId?: string;
+    email?: string;
+    phone?: string;
+    name?: string;
+    /**
+     * `HMAC-SHA256(<your channel's IDV secret>, externalId)`, computed by YOUR
+     * SERVER. Never compute it in the browser — the secret would be in your
+     * page source. Required when the channel has identity verification enabled
+     * and you are claiming an `externalId`; ignored when it does not.
+     */
+    userHash?: string;
+    attributes?: Record<string, unknown>;
+}
+export interface TrackInput {
+    name: string;
+    properties?: Record<string, unknown>;
+}
+declare global {
+    interface Window {
+        Chatly?: {
+            open?: () => void;
+            close?: () => void;
+            destroy?: () => void;
+        };
+    }
+}
+/**
+ * An uploaded file, as returned by `uploadFile` and accepted by `send`.
+ *
+ * Declared locally rather than imported from `@livechat/shared`: this bundle
+ * ships to a customer's website, and importing from the shared package drags
+ * zod into it — measured at ~11KB gzipped when it happened to the widget.
+ */
+export interface VisitorAttachment {
+    readonly id: string;
+    readonly filename: string;
+    readonly mimeType: string;
+    readonly sizeBytes: number;
+    readonly url: string;
+}
+export declare class Chatly {
+    private readonly opts;
+    private readonly base;
+    private visitorToken;
+    /**
+     * The realtime host `/v1/widget/init` reported, remembered for `subscribe`.
+     *
+     * `/v1/widget/realtime/token` returns `{ token, expiresAt }` and NO url —
+     * the first version of `subscribe` read a `url` off it and silently fell
+     * back to the API host, which is not where the socket server is.
+     */
+    private realtimeUrl;
+    /**
+     * This visitor's contact id, remembered for the typing event — the realtime
+     * gateway's payload requires an `actorId` and the visitor's is their contact.
+     */
+    private contactId;
+    static init(opts: SdkOptions): Chatly;
+    private constructor();
+    open(): void;
+    close(): void;
+    /**
+     * Attach a known identity to this visitor.
+     *
+     * Re-initialises the session with an `identity` payload rather than calling
+     * a dedicated endpoint. There has never been a `/v1/widget/identify` route —
+     * this method has 404'd since it was written, as have the Kotlin and Swift
+     * equivalents. Identity is accepted by `init`, which is also where the
+     * `userHash` check for verified identity lives, so routing through it means
+     * identification and verification cannot drift apart.
+     *
+     * `identify({ email })` with no `externalId` — the exact call this file's
+     * own header comment demonstrates — used to be rejected by the server with
+     * a 400, because `widgetInitSchema` required `externalId`. It no longer is;
+     * an email-only identity attaches a reply address to whoever this browser
+     * already is. It cannot be *verified*, though: `userHash` binds the external
+     * id and there is nothing to bind without one.
+     *
+     * No longer mints an anonymous session first. That cost a round trip, and
+     * worse, it was pointless: the token the server returns HERE is the
+     * identified one, and it is stored below. Before, the SDK kept the
+     * anonymous token it had just fetched, so every later `track` or `send`
+     * spoke for the anonymous visitor and the identification was quietly lost.
+     */
+    identify(input: IdentifyInput): Promise<{
+        contactId: string;
+    }>;
+    /**
+     * Upload a file as this visitor and return the attachment record.
+     *
+     * The two-step presign + direct PUT is deliberate: the file never passes
+     * through the API, which would mean proxying it in memory only to write it
+     * to object storage anyway.
+     */
+    uploadFile(file: File): Promise<VisitorAttachment>;
+    /** Send a message, optionally with attachments from `uploadFile`. */
+    send(conversationId: string, body: string, attachments?: VisitorAttachment[]): Promise<void>;
+    /**
+     * This visitor's own conversations, most recent first.
+     *
+     * Scoped by the visitor token, so it is exactly the threads this browser is
+     * entitled to and never anyone else's.
+     */
+    listConversations(limit?: number): Promise<HeadlessConversation[]>;
+    /** The messages of one conversation, oldest first. */
+    listMessages(conversationId: string, limit?: number): Promise<HeadlessMessage[]>;
+    /**
+     * Open a NEW conversation with a first message.
+     *
+     * `send` replies to one that exists and requires a `conversationId`; this is
+     * the other endpoint. Getting them the wrong way round is a 400 complaining
+     * about a missing `conversationId`, which is how the repo's own E2E spec was
+     * written and why it could never pass.
+     */
+    startConversation(body: string, attachments?: VisitorAttachment[]): Promise<{
+        conversationId: string;
+    }>;
+    /**
+     * Call `onMessage` for every message this subscription has not already
+     * given you. Returns the unsubscribe function.
+     *
+     * **Polling by default**, because the alternative is making every consumer
+     * ship `socket.io-client` whether they want push or not. Pass your own
+     * factory for push:
+     *
+     *     import { io } from 'socket.io-client';
+     *     const stop = chatly.subscribe(id, { onMessage }, { io });
+     *
+     * Errors go to `onError`, never a rejected promise: this is long-lived, and
+     * a rejection nobody awaits is an unhandled rejection on the customer's own
+     * page.
+     */
+    subscribe(conversationId: string, handlers: SubscribeHandlers, options?: SubscribeOptions): Subscription;
+    /** Submit a post-chat satisfaction score (1-5, or 0-10 for NPS). */
+    rate(conversationId: string, score: number, comment?: string): Promise<void>;
+    /** Email this visitor a transcript of their conversation. */
+    emailTranscript(conversationId: string, email: string): Promise<void>;
+    track(name: string, properties?: Record<string, unknown>): Promise<void>;
+    private setVisitorToken;
+    private ensureVisitorToken;
+    private request;
+}
+export default Chatly;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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