@isnap/sdk 2.3.1 → 2.4.0-next.43972422309.1
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/CHANGELOG.md +15 -0
- package/README.md +92 -7
- package/dist/chat-sdk/adapter.d.ts +175 -0
- package/dist/chat-sdk/adapter.d.ts.map +1 -0
- package/dist/chat-sdk/adapter.js +395 -0
- package/dist/chat-sdk/adapter.js.map +1 -0
- package/dist/chat-sdk/format.d.ts +12 -0
- package/dist/chat-sdk/format.d.ts.map +1 -0
- package/dist/chat-sdk/format.js +15 -0
- package/dist/chat-sdk/format.js.map +1 -0
- package/dist/chat-sdk/index.d.ts +14 -0
- package/dist/chat-sdk/index.d.ts.map +1 -0
- package/dist/chat-sdk/index.js +11 -0
- package/dist/chat-sdk/index.js.map +1 -0
- package/dist/chat-sdk/reactions.d.ts +10 -0
- package/dist/chat-sdk/reactions.d.ts.map +1 -0
- package/dist/chat-sdk/reactions.js +34 -0
- package/dist/chat-sdk/reactions.js.map +1 -0
- package/dist/chat-sdk/thread-id.d.ts +16 -0
- package/dist/chat-sdk/thread-id.d.ts.map +1 -0
- package/dist/chat-sdk/thread-id.js +20 -0
- package/dist/chat-sdk/thread-id.js.map +1 -0
- package/dist/client.d.ts +2 -0
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +3 -0
- package/dist/client.js.map +1 -1
- package/dist/generated/openapi.d.ts +1567 -96
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/resources/chats.d.ts +3 -1
- package/dist/resources/chats.d.ts.map +1 -1
- package/dist/resources/chats.js +3 -1
- package/dist/resources/chats.js.map +1 -1
- package/dist/resources/fleet.d.ts +23 -0
- package/dist/resources/fleet.d.ts.map +1 -0
- package/dist/resources/fleet.js +20 -0
- package/dist/resources/fleet.js.map +1 -0
- package/dist/resources/lines.d.ts +32 -2
- package/dist/resources/lines.d.ts.map +1 -1
- package/dist/resources/lines.js +24 -0
- package/dist/resources/lines.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/webhooks/types.d.ts +1 -1
- package/dist/webhooks/types.d.ts.map +1 -1
- package/dist/webhooks/types.js.map +1 -1
- package/examples/chat-sdk-bot.ts +91 -0
- package/package.json +18 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@isnap/sdk` are documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
4
4
|
|
|
5
|
+
## [2.4.0]
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- `@isnap/sdk/chat-sdk`: an adapter that plugs a bot built with the Vercel Chat SDK into an iSnap line. `createISnapAdapter()` (and the `ISnapAdapter` class) reads `ISNAP_API_KEY` and `ISNAP_WEBHOOK_SECRET` or takes `apiKey` and `webhookSecret`, and registers under the name `isnap`.
|
|
9
|
+
- A `message.received` webhook, verified with the same checks as `verifyWebhook`, reaches the bot's handlers as a message whose thread id is `isnap:` followed by the iSnap `chat_id` and whose id is the iSnap message id. A request with a missing or wrong signature gets `401` and reaches no handler. Every other event type is acknowledged and ignored.
|
|
10
|
+
- `thread.post` calls `messages.send` on the line and the contact of the chat, with a new idempotency key for each post. The adapter never sets `use_typing_indicator`, so the line's default applies.
|
|
11
|
+
- Typing maps to `chats.typingStart` and `chats.typingStop`. Reactions map to `messages.addReaction` and `messages.removeReaction` with the six iSnap types.
|
|
12
|
+
- A reaction the message cannot take (`sms_reactions_not_supported`, `multi_attachment_reaction`, `reaction_recipient_unsupported`) and a typing indicator a chat cannot show (`sms_typing_not_supported`, `unsupported_handle`) resolve without an error and go to the `onUnsupported` option. A typing indicator that iSnap drops on a shared line is a success.
|
|
13
|
+
- Exports: `createISnapAdapter`, `ISnapAdapter`, `ISnapFormatConverter`, `encodeThreadId`, `decodeThreadId`, `toISnapReaction`, `ADAPTER_NAME` and the types `ISnapAdapterConfig`, `ISnapChatClient`, `ISnapRawMessage`, `ISnapUnsupported`, `ISnapThreadId` and `ISnapReactionType`.
|
|
14
|
+
- `examples/chat-sdk-bot.ts`: a Chat SDK bot that likes each message it receives and answers it. `README.md` has a Chat SDK adapter section with the setup and how to run the example on a line of your own.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- `package.json` declares the `./chat-sdk` export and `chat` (`^4.0.0`) as an optional peer dependency. `@isnap/sdk` still has no runtime dependency, and a project that does not import `@isnap/sdk/chat-sdk` installs and imports the package without `chat`. Importing `@isnap/sdk/chat-sdk` needs `chat` and a Chat SDK state adapter in your project.
|
|
18
|
+
- The compiled code of the `@isnap/sdk` entry point is the code of 2.3.1, apart from the version string.
|
|
19
|
+
|
|
5
20
|
## [2.3.1]
|
|
6
21
|
|
|
7
22
|
Documentation, type declarations and package metadata. The compiled code is the code of 2.3.0, apart from the version string: no method changes behavior.
|
package/README.md
CHANGED
|
@@ -10,16 +10,16 @@ The full documentation is at [docs.isnap.ai](https://docs.isnap.ai). For help, w
|
|
|
10
10
|
npm install @isnap/sdk
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
`bun add`, `pnpm add` and `yarn add` work the same way. The package has no runtime dependency.
|
|
13
|
+
`bun add`, `pnpm add` and `yarn add` work the same way. The package has no runtime dependency. The Chat SDK adapter needs the `chat` package: see [Chat SDK adapter](#chat-sdk-adapter).
|
|
14
14
|
|
|
15
15
|
## Requirements
|
|
16
16
|
|
|
17
17
|
- **Runtime.** Node.js 20 or later, or Bun 1.2 or later.
|
|
18
|
-
- **Module format.** The package is ESM only, with
|
|
18
|
+
- **Module format.** The package is ESM only, with named exports and two entry points: `@isnap/sdk` and `@isnap/sdk/chat-sdk`. In Node.js, `require('@isnap/sdk')` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`: from CommonJS code, load the package with `await import('@isnap/sdk')`.
|
|
19
19
|
- **Server side.** The SDK does not build for a browser. An API key is a secret: keep it on your server.
|
|
20
20
|
- **TypeScript.** Type declarations are bundled. They use web platform types such as `HeadersInit` and `Blob`, so your `tsconfig.json` needs `"DOM"` in `lib` (for example `"lib": ["ES2022", "DOM"]`), or `"skipLibCheck": true`. Set `moduleResolution` to `bundler`, `node16` or `nodenext`.
|
|
21
21
|
|
|
22
|
-
The
|
|
22
|
+
The client reads no environment variable. The key and every setting come from the options you pass. Only the Chat SDK adapter reads `ISNAP_API_KEY` and `ISNAP_WEBHOOK_SECRET`, when you do not pass them.
|
|
23
23
|
|
|
24
24
|
## First call
|
|
25
25
|
|
|
@@ -92,11 +92,12 @@ Every method takes a last optional argument:
|
|
|
92
92
|
| `client.chats` | `list`, `get`, `typingStart`, `typingStop`, `markRead`, `shareContactCard` |
|
|
93
93
|
| `client.attachments` | `create`, `get`, and the [`upload` helper](#attachments-helper) |
|
|
94
94
|
| `client.lookup` | `check`: whether a handle can receive iMessage |
|
|
95
|
-
| `client.lines` | `list`, `listMine`, `get`, `reserve`, `activate`, `release`, `assign`, `mintShared`, `patch`, `terminate`, `cancel`, `uncancel`, `setAnniversary`, `setVariant`, `cancelVariantChange`, `convertToTest`, `convertFromTest`, `transferOwnership`, `getConfig`, `updateConfig`, `quota`, `queue`, `health`, `createInvite` |
|
|
95
|
+
| `client.lines` | `list`, `listMine`, `get`, `reserve`, `activate`, `release`, `assign`, `mintShared`, `patch`, `terminate`, `cancel`, `uncancel`, `setAnniversary`, `setVariant`, `cancelVariantChange`, `convertToTest`, `convertFromTest`, `transferOwnership`, `getConfig`, `updateConfig`, `quota`, `queue`, `health`, `healthReport`, `createInvite` |
|
|
96
96
|
| `client.preOrders` | `create`, `confirm`, `list`, `get`, `update`, `cancel` |
|
|
97
97
|
| `client.areaCodes` | `list`: the area codes a pre-order can request |
|
|
98
98
|
| `client.byod` | `pair`: an activation code for the bridge app on your own Mac and iPhone |
|
|
99
99
|
| `client.apps` | `manifest`: the download links of the bridge app |
|
|
100
|
+
| `client.fleet` | `health`: the public two-way rate report of the fleet |
|
|
100
101
|
| `client.macosSessions` | `rent`, `get`, `update`, `cancel`, `uncancel` |
|
|
101
102
|
| `client.trial` | `init`, `status`, `activity`, `revoke`, `get`, `update` |
|
|
102
103
|
| `client.webhooks` | `create`, `list`, `get`, `update`, `delete`, `rotateSecret`, `deliveries`, `replay`, `events` |
|
|
@@ -388,6 +389,89 @@ Every `data` also carries `metadata` and `line_metadata`. A new event type in a
|
|
|
388
389
|
|
|
389
390
|
`parseWebhookEvent(rawBody)` applies the same checks to the body without verifying a signature.
|
|
390
391
|
|
|
392
|
+
## Chat SDK adapter
|
|
393
|
+
|
|
394
|
+
`@isnap/sdk/chat-sdk` plugs a bot built with the [Vercel Chat SDK](https://chat-sdk.dev) into an iSnap line. The bot receives the messages the line receives, and what it posts leaves from the same line, as an iMessage, RCS or SMS message: the line's device chooses the service, as for any message sent with `messages.send`.
|
|
395
|
+
|
|
396
|
+
The adapter needs the Chat SDK (`chat` 4.x) and a state adapter, which `@isnap/sdk` does not install. A project that never imports `@isnap/sdk/chat-sdk` needs neither.
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
npm install @isnap/sdk chat @chat-adapter/state-memory
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
`@chat-adapter/state-memory` keeps state in process memory: use a persistent state adapter in production.
|
|
403
|
+
|
|
404
|
+
### Set it up
|
|
405
|
+
|
|
406
|
+
```ts
|
|
407
|
+
import { createMemoryState } from '@chat-adapter/state-memory'
|
|
408
|
+
import { Chat } from 'chat'
|
|
409
|
+
import { createISnapAdapter } from '@isnap/sdk/chat-sdk'
|
|
410
|
+
|
|
411
|
+
const bot = new Chat({
|
|
412
|
+
userName: 'my-bot',
|
|
413
|
+
adapters: { isnap: createISnapAdapter() },
|
|
414
|
+
state: createMemoryState()
|
|
415
|
+
})
|
|
416
|
+
|
|
417
|
+
bot.onDirectMessage(async (thread, message) => {
|
|
418
|
+
await thread.post(`You said: ${message.text}`)
|
|
419
|
+
})
|
|
420
|
+
|
|
421
|
+
// In the route that receives the webhook deliveries:
|
|
422
|
+
export async function POST(request: Request) {
|
|
423
|
+
return bot.webhooks.isnap(request)
|
|
424
|
+
}
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
Every iSnap chat is a direct message between the line and one contact, so register your handlers with `onDirectMessage`.
|
|
428
|
+
|
|
429
|
+
1. Create a webhook subscription (`client.webhooks.create`) for the public URL of your route, with the event `message.received`. Keep the `secret` it returns.
|
|
430
|
+
2. Give the adapter the API key and that secret. `createISnapAdapter` reads `ISNAP_API_KEY` and `ISNAP_WEBHOOK_SECRET`; the options `apiKey` and `webhookSecret` take precedence. Neither value is logged. During a secret rotation, pass `webhookSecret: [newSecret, oldSecret]`.
|
|
431
|
+
3. The API key must be able to send on the line: a line-scoped key needs that line in its `line_ids`.
|
|
432
|
+
|
|
433
|
+
`createISnapAdapter(config?)` also takes `baseUrl`, `client` (an `ISnapClient` you built, in place of `apiKey` and `baseUrl`), `userName`, `logger`, `webhookTolerance` (seconds, default 300), `fetch` (used to download received attachments) and `onUnsupported`.
|
|
434
|
+
|
|
435
|
+
### What the adapter does
|
|
436
|
+
|
|
437
|
+
| Chat SDK | iSnap |
|
|
438
|
+
| --- | --- |
|
|
439
|
+
| Incoming webhook | Verifies the delivery as `verifyWebhook` does. A request with a missing or wrong signature, or a timestamp outside `webhookTolerance`, gets `401` and reaches no handler. A `message.received` event goes to your handlers. Every other event type gets `200` and is ignored. |
|
|
440
|
+
| Thread id | `isnap:` followed by the iSnap `chat_id`. `decodeThreadId(thread.id).chatId` gives the `chat_id` back. |
|
|
441
|
+
| Message id | The iSnap message id (`msg_...`). |
|
|
442
|
+
| `message.raw` | The `data` of the event: `message`, `chat_id` and, when the device reports them, `contact_name` and `received_at`. |
|
|
443
|
+
| `thread.post(...)` | `messages.send` on the line and the contact of the chat, with a new `Idempotency-Key` for each post. The adapter never sets `use_typing_indicator`: the line's default applies. Only text is sent. Markdown is sent as plain text. Posting to a group chat, posting a file, editing a message and deleting a message are refused with a `NotImplementedError`. |
|
|
444
|
+
| `thread.startTyping()` | `chats.typingStart`. The adapter's `endTyping` is `chats.typingStop`. |
|
|
445
|
+
| Reactions | `messages.addReaction` and `messages.removeReaction`, with iSnap's six types: `thumbs_up` is `like`, `thumbs_down` is `dislike`, `heart` is `love`, `laugh` is `laugh`, `exclamation` is `emphasize`, `question` is `question`. The emoji and the iSnap names work too. A line has one reaction per message, so `removeReaction` ignores the emoji. |
|
|
446
|
+
| `fetchMessages` | The messages of the chat that iSnap still keeps, oldest first in each page. |
|
|
447
|
+
|
|
448
|
+
Received files are attachments of the message: `fetchData()` downloads the file.
|
|
449
|
+
|
|
450
|
+
iSnap retries a failed delivery with the same message id, and the Chat SDK passes that message to your handlers once.
|
|
451
|
+
|
|
452
|
+
### What the adapter does not throw
|
|
453
|
+
|
|
454
|
+
An SMS or RCS message takes no reaction (`sms_reactions_not_supported`), and some chats take no typing indicator (`sms_typing_not_supported`, `unsupported_handle`). The adapter resolves those calls without an error, so a handler that reacts or types never fails the bot for it. It writes one warning to the logger and calls `onUnsupported({ capability, reason, threadId, messageId? })`, where `reason` is the iSnap error code, or `unmapped_emoji` for an emoji iSnap has no reaction for:
|
|
455
|
+
|
|
456
|
+
```ts
|
|
457
|
+
createISnapAdapter({
|
|
458
|
+
onUnsupported: ({ capability, reason }) => console.log('not applied:', capability, reason)
|
|
459
|
+
})
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
A typing indicator that iSnap drops, on a shared line or on a line with no paired device, is a success, not an error. Every other error of the API (an inactive line, an invalid key, a quota) is thrown to your handler as the SDK's error classes.
|
|
463
|
+
|
|
464
|
+
### Run the example
|
|
465
|
+
|
|
466
|
+
`examples/chat-sdk-bot.ts` is a bot that likes every message it receives and answers it with `You said: ...`. To run it on a line of your own:
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
cp node_modules/@isnap/sdk/examples/chat-sdk-bot.ts .
|
|
470
|
+
ISNAP_API_KEY=isnap_live_... ISNAP_WEBHOOK_SECRET=whsec_... bun run chat-sdk-bot.ts
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
It listens on the port in `PORT` (default 3002) at `/webhooks/isnap`. Expose that URL, subscribe it to `message.received` as above, then send a message to the line from a phone. The bot sends real messages from your line.
|
|
474
|
+
|
|
391
475
|
## Attachments helper
|
|
392
476
|
|
|
393
477
|
`attachments.upload(file, { filename, contentType }, opts?)` registers the attachment, uploads the bytes to the URL the API returns, then reads the attachment until its `status` is `ready`, and resolves with it.
|
|
@@ -446,7 +530,7 @@ The SDK stores nothing. It passes phone numbers, handles, message bodies and met
|
|
|
446
530
|
|
|
447
531
|
## Examples
|
|
448
532
|
|
|
449
|
-
The package ships
|
|
533
|
+
The package ships five scripts in its `examples` directory:
|
|
450
534
|
|
|
451
535
|
| File | What it does |
|
|
452
536
|
| --- | --- |
|
|
@@ -454,15 +538,16 @@ The package ships four scripts in its `examples` directory:
|
|
|
454
538
|
| `examples/paginate-messages.ts` | Reads the messages of a line with the iterator and an `AbortSignal`. |
|
|
455
539
|
| `examples/upload-attachment.ts` | Uploads a file and sends it as an attachment. |
|
|
456
540
|
| `examples/handle-webhook.ts` | Runs a `node:http` server that verifies deliveries, deduplicates on `event_id` and branches on the event family. |
|
|
541
|
+
| `examples/chat-sdk-bot.ts` | Runs a Chat SDK bot on a line: it likes each message it receives and answers it. See [Chat SDK adapter](#chat-sdk-adapter). |
|
|
457
542
|
|
|
458
|
-
They import `@isnap/sdk` like your own code. Copy one into your project and run it, for example with Bun:
|
|
543
|
+
They import `@isnap/sdk` (and `@isnap/sdk/chat-sdk`) like your own code. Copy one into your project and run it, for example with Bun:
|
|
459
544
|
|
|
460
545
|
```bash
|
|
461
546
|
cp node_modules/@isnap/sdk/examples/send-message.ts .
|
|
462
547
|
ISNAP_API_KEY=isnap_live_... ISNAP_LINE_ID=line_... ISNAP_TO=+14155550123 bun run send-message.ts
|
|
463
548
|
```
|
|
464
549
|
|
|
465
|
-
|
|
550
|
+
All but `handle-webhook.ts` call `https://api.isnap.ai` with your key. `send-message.ts`, `upload-attachment.ts` and `chat-sdk-bot.ts` send real messages.
|
|
466
551
|
|
|
467
552
|
## Help
|
|
468
553
|
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
import { Message as ChatMessage } from 'chat';
|
|
2
|
+
import type { Adapter, AdapterPostableMessage, ChatInstance, EmojiValue, FetchOptions, FetchResult, FormattedContent, Logger, RawMessage, ThreadInfo, WebhookOptions } from 'chat';
|
|
3
|
+
import { ISnapClient } from '../client.js';
|
|
4
|
+
import type { AttachmentsResource } from '../resources/attachments.js';
|
|
5
|
+
import type { ChatsResource } from '../resources/chats.js';
|
|
6
|
+
import type { Message as ISnapMessage, MessagesResource } from '../resources/messages.js';
|
|
7
|
+
import type { ISnapThreadId } from './thread-id.js';
|
|
8
|
+
/**
|
|
9
|
+
* The part of `ISnapClient` the adapter calls. An `ISnapClient` satisfies it;
|
|
10
|
+
* a test can pass a fake that implements only these members.
|
|
11
|
+
*/
|
|
12
|
+
export interface ISnapChatClient {
|
|
13
|
+
messages: Pick<MessagesResource, 'send' | 'addReaction' | 'removeReaction'>;
|
|
14
|
+
chats: Pick<ChatsResource, 'get' | 'typingStart' | 'typingStop'>;
|
|
15
|
+
attachments: Pick<AttachmentsResource, 'get'>;
|
|
16
|
+
request: ISnapClient['request'];
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* What the Chat SDK hands to your handlers as `message.raw`: the `data` of the
|
|
20
|
+
* `message.received` event, narrowed to the fields the adapter reads.
|
|
21
|
+
*/
|
|
22
|
+
export interface ISnapRawMessage {
|
|
23
|
+
/** The message, as `messages.get` returns it. */
|
|
24
|
+
message: ISnapMessage;
|
|
25
|
+
/** The `chat_` id of the conversation. It is also the thread id, after `isnap:`. */
|
|
26
|
+
chat_id: string;
|
|
27
|
+
/** The contact's name in the line device's address book, when the device reports one. */
|
|
28
|
+
contact_name?: string;
|
|
29
|
+
/** When the line's device received the message. */
|
|
30
|
+
received_at?: string;
|
|
31
|
+
}
|
|
32
|
+
/** A capability iSnap did not apply, reported to `onUnsupported` instead of thrown. */
|
|
33
|
+
export interface ISnapUnsupported {
|
|
34
|
+
capability: 'reaction' | 'typing';
|
|
35
|
+
/** The iSnap `error.code` that refused the call, or `unmapped_emoji` for an emoji with no iSnap reaction. */
|
|
36
|
+
reason: string;
|
|
37
|
+
threadId: string;
|
|
38
|
+
/** The message a reaction was meant for. */
|
|
39
|
+
messageId?: string;
|
|
40
|
+
}
|
|
41
|
+
export interface ISnapAdapterConfig {
|
|
42
|
+
/** Your iSnap API key. Falls back to the `ISNAP_API_KEY` environment variable. Unused when `client` is set. */
|
|
43
|
+
apiKey?: string;
|
|
44
|
+
/**
|
|
45
|
+
* The signing secret of your webhook subscription (`whsec_...`), as the API
|
|
46
|
+
* returned it. Falls back to the `ISNAP_WEBHOOK_SECRET` environment
|
|
47
|
+
* variable. Pass an array, `[newSecret, oldSecret]`, while you rotate it.
|
|
48
|
+
*/
|
|
49
|
+
webhookSecret?: string | readonly string[];
|
|
50
|
+
/** The API base URL. Default `https://api.isnap.ai`. Unused when `client` is set. */
|
|
51
|
+
baseUrl?: string;
|
|
52
|
+
/** A client you already built, in place of `apiKey` and `baseUrl`. */
|
|
53
|
+
client?: ISnapChatClient;
|
|
54
|
+
/** The bot's name in the Chat SDK. Default `isnap-bot`. */
|
|
55
|
+
userName?: string;
|
|
56
|
+
/** A Chat SDK logger. The `Chat` instance replaces it with its own when it starts the adapter. */
|
|
57
|
+
logger?: Logger;
|
|
58
|
+
/** Largest accepted age of a webhook delivery, in seconds. Default 300. */
|
|
59
|
+
webhookTolerance?: number;
|
|
60
|
+
/** `fetch` for downloading received attachments. Default: the global `fetch`. */
|
|
61
|
+
fetch?: typeof fetch;
|
|
62
|
+
/**
|
|
63
|
+
* Called when a reaction or a typing indicator cannot be applied: an SMS or
|
|
64
|
+
* RCS message takes no reaction, a chat without an iMessage line or a
|
|
65
|
+
* phone-number handle takes no typing indicator. The call resolves without
|
|
66
|
+
* an error either way; use this to count or show the gap.
|
|
67
|
+
*/
|
|
68
|
+
onUnsupported?: (info: ISnapUnsupported) => void;
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* A Chat SDK adapter for an iSnap line: your bot receives the messages a line
|
|
72
|
+
* receives, and its replies leave from the same line.
|
|
73
|
+
*
|
|
74
|
+
* The thread id is `isnap:` followed by the iSnap `chat_id`
|
|
75
|
+
* (`encodeThreadId`, `decodeThreadId`), and the id of a message is its iSnap
|
|
76
|
+
* message id. Build it with `createISnapAdapter` and register it under the
|
|
77
|
+
* name `isnap`.
|
|
78
|
+
*/
|
|
79
|
+
export declare class ISnapAdapter implements Adapter<ISnapThreadId, ISnapRawMessage> {
|
|
80
|
+
readonly name = "isnap";
|
|
81
|
+
readonly userName: string;
|
|
82
|
+
private chat;
|
|
83
|
+
private logger;
|
|
84
|
+
private readonly client;
|
|
85
|
+
private readonly secrets;
|
|
86
|
+
private readonly webhookTolerance;
|
|
87
|
+
private readonly fetchFile;
|
|
88
|
+
private readonly onUnsupported;
|
|
89
|
+
private readonly converter;
|
|
90
|
+
private readonly routes;
|
|
91
|
+
constructor(config?: ISnapAdapterConfig);
|
|
92
|
+
initialize(chat: ChatInstance): Promise<void>;
|
|
93
|
+
encodeThreadId(platformData: ISnapThreadId): string;
|
|
94
|
+
decodeThreadId(threadId: string): ISnapThreadId;
|
|
95
|
+
channelIdFromThreadId(threadId: string): string;
|
|
96
|
+
/** Every iSnap chat is a conversation between a line and its contact. */
|
|
97
|
+
isDM(): boolean;
|
|
98
|
+
renderFormatted(content: FormattedContent): string;
|
|
99
|
+
/**
|
|
100
|
+
* Handle one webhook delivery from iSnap. Mount it on the route you gave
|
|
101
|
+
* the webhook subscription: `chat.webhooks.isnap(request)` does.
|
|
102
|
+
*
|
|
103
|
+
* The signature is verified first. A request with a missing or wrong
|
|
104
|
+
* signature, a stale timestamp or an unreadable body gets `401` and reaches
|
|
105
|
+
* no handler. A `message.received` event is passed to the bot; every other
|
|
106
|
+
* event type is acknowledged with `200` and ignored. A retry of a delivery
|
|
107
|
+
* carries the same message id, which the Chat SDK deduplicates.
|
|
108
|
+
*/
|
|
109
|
+
handleWebhook(request: Request, options?: WebhookOptions): Promise<Response>;
|
|
110
|
+
parseMessage(raw: ISnapRawMessage): ChatMessage<ISnapRawMessage>;
|
|
111
|
+
/**
|
|
112
|
+
* Send a reply into the thread's chat, from the chat's line. The line's
|
|
113
|
+
* typing-indicator default applies: the adapter never sets
|
|
114
|
+
* `use_typing_indicator`. Every call carries its own `Idempotency-Key`, so
|
|
115
|
+
* the SDK's automatic retries cannot send the reply twice.
|
|
116
|
+
*
|
|
117
|
+
* Only text is sent. A group chat, a file and a card with no text are
|
|
118
|
+
* refused with a `NotImplementedError`.
|
|
119
|
+
*/
|
|
120
|
+
postMessage(threadId: string, message: AdapterPostableMessage): Promise<RawMessage<ISnapRawMessage>>;
|
|
121
|
+
/** iMessage has no edit that the API exposes. */
|
|
122
|
+
editMessage(): Promise<RawMessage<ISnapRawMessage>>;
|
|
123
|
+
/** A message that has left the line cannot be taken back. */
|
|
124
|
+
deleteMessage(): Promise<void>;
|
|
125
|
+
/**
|
|
126
|
+
* Put the line's reaction on a message. Chat SDK emoji map to iSnap's six
|
|
127
|
+
* reactions (`love`, `like`, `dislike`, `laugh`, `emphasize`, `question`).
|
|
128
|
+
* A reaction the message cannot take (an SMS or RCS message, an emoji with
|
|
129
|
+
* no iSnap reaction) resolves without an error and goes to `onUnsupported`.
|
|
130
|
+
*/
|
|
131
|
+
addReaction(threadId: string, messageId: string, emoji: EmojiValue | string): Promise<void>;
|
|
132
|
+
/**
|
|
133
|
+
* Remove the line's reaction from a message. iSnap holds one reaction per
|
|
134
|
+
* line and message, so the emoji is not used. The refusals of `addReaction`
|
|
135
|
+
* resolve without an error.
|
|
136
|
+
*/
|
|
137
|
+
removeReaction(threadId: string, messageId: string, _emoji: EmojiValue | string): Promise<void>;
|
|
138
|
+
/**
|
|
139
|
+
* Show the typing indicator. iSnap accepts the call and drops it on a
|
|
140
|
+
* shared line and on a line with no paired device: that is not an error. A
|
|
141
|
+
* chat that cannot show it (an SMS or RCS chat, a contact that is not a
|
|
142
|
+
* phone number) resolves without an error and goes to `onUnsupported`.
|
|
143
|
+
*/
|
|
144
|
+
startTyping(threadId: string): Promise<void>;
|
|
145
|
+
/** Clear the typing indicator, with the same tolerance as `startTyping`. */
|
|
146
|
+
endTyping(threadId: string): Promise<void>;
|
|
147
|
+
/**
|
|
148
|
+
* The messages of the chat that iSnap still keeps, oldest first within the
|
|
149
|
+
* page. `backward` (default) starts from the newest message.
|
|
150
|
+
*/
|
|
151
|
+
fetchMessages(threadId: string, options?: FetchOptions): Promise<FetchResult<ISnapRawMessage>>;
|
|
152
|
+
fetchThread(threadId: string): Promise<ThreadInfo>;
|
|
153
|
+
private routeOf;
|
|
154
|
+
private toAttachment;
|
|
155
|
+
private isRefusal;
|
|
156
|
+
private unsupported;
|
|
157
|
+
}
|
|
158
|
+
/**
|
|
159
|
+
* Build the adapter. The API key and the webhook signing secret come from
|
|
160
|
+
* `config` or from the `ISNAP_API_KEY` and `ISNAP_WEBHOOK_SECRET` environment
|
|
161
|
+
* variables; neither is ever logged.
|
|
162
|
+
*
|
|
163
|
+
* ```ts
|
|
164
|
+
* import { Chat } from 'chat'
|
|
165
|
+
* import { createISnapAdapter } from '@isnap/sdk/chat-sdk'
|
|
166
|
+
*
|
|
167
|
+
* const bot = new Chat({
|
|
168
|
+
* userName: 'bot',
|
|
169
|
+
* adapters: { isnap: createISnapAdapter() },
|
|
170
|
+
* state
|
|
171
|
+
* })
|
|
172
|
+
* ```
|
|
173
|
+
*/
|
|
174
|
+
export declare function createISnapAdapter(config?: ISnapAdapterConfig): ISnapAdapter;
|
|
175
|
+
//# sourceMappingURL=adapter.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/chat-sdk/adapter.ts"],"names":[],"mappings":"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"}
|