feat: add Comms provider

.changeset/add-comms-provider.md

@@ -0,0 +1,8 @@
+---
+'@imessage-sdk/comms': minor
+'imessage-cli': minor
+---
+
+Add Comms by Osis as an official provider with direct text sending, idempotency, conversation
+continuation, provider-specific read APIs, and webhook endpoint management. Bundle the provider
+with `imessage-cli`.

.env.example

@@ -6,6 +6,9 @@ BLOOIO_TEST_IMAGE_URL=
 BLOOIO_TEST_VIDEO_URL=
 BLOOIO_TEST_FILE_URL=
 
+COMMS_API_KEY=
+COMMS_TEST_RECIPIENT=
+
 PHOTON_PROJECT_ID=
 PHOTON_PROJECT_SECRET=
 PHOTON_PHONE_NUMBER=

README.md

@@ -25,7 +25,7 @@ const client = createIMessageClient({
 
 P.S. remember to create your own [Blooio account](https://app.blooio.com/signup?ref=BLOO-2NS4AJM8) and configure the provider with your credentials.
 
-The stable v0.1 providers are Blooio, Photon, and Sendblue. See the
+The official providers are Blooio, Comms by Osis, Photon, and Sendblue. See the
 [provider feature matrix](./packages/providers/README.md) for their verified surfaces and current
 limitations.
 
@@ -60,6 +60,7 @@ packages/
 ├── imessage-sdk/          Provider-neutral core package
 ├── providers/
 │   ├── blooio/            @imessage-sdk/blooio
+│   ├── comms/             @imessage-sdk/comms
 │   ├── photon/            @imessage-sdk/photon
 │   └── sendblue/          @imessage-sdk/sendblue
 ├── chat-adapter/          @imessage-sdk/chat-adapter

RELEASING.md

@@ -9,6 +9,7 @@ requests, npm trusted publishing, and package-specific GitHub Releases.
 | ----------------------------- | ---------------------------- | ------ |
 | `packages/imessage-sdk`       | `imessage-sdk`               | Public |
 | `packages/providers/blooio`   | `@imessage-sdk/blooio`       | Public |
+| `packages/providers/comms`    | `@imessage-sdk/comms`        | Public |
 | `packages/providers/photon`   | `@imessage-sdk/photon`       | Public |
 | `packages/providers/sendblue` | `@imessage-sdk/sendblue`     | Public |
 | `packages/chat-adapter`       | `@imessage-sdk/chat-adapter` | Public |
@@ -101,8 +102,8 @@ changelogs.
 ## Trusted publishing on npm
 
 Configure trusted publishing separately in the settings for `imessage-sdk`,
-`@imessage-sdk/blooio`, `@imessage-sdk/photon`, `@imessage-sdk/sendblue`, and
-`@imessage-sdk/chat-adapter`, and `imessage-cli`:
+`@imessage-sdk/blooio`, `@imessage-sdk/comms`, `@imessage-sdk/photon`,
+`@imessage-sdk/sendblue`, `@imessage-sdk/chat-adapter`, and `imessage-cli`:
 
 ```text
 Provider: GitHub Actions
@@ -173,12 +174,12 @@ npm publish "$PACKAGE_DIR/imessage-cli-0.1.0-beta.0.tgz" \
   --provenance=false
 ```
 
-Add `--tag beta` when bootstrapping a prerelease. For the initial stable Sendblue release, use:
+Add `--tag beta` when bootstrapping a prerelease. For an initial stable provider release, use:
 
 ```bash
 PACKAGE_DIR=$(mktemp -d)
-pnpm --filter @imessage-sdk/sendblue pack --pack-destination "$PACKAGE_DIR"
-npm publish "$PACKAGE_DIR/imessage-sdk-sendblue-0.1.0.tgz" \
+pnpm --filter @imessage-sdk/<provider> pack --pack-destination "$PACKAGE_DIR"
+npm publish "$PACKAGE_DIR/imessage-sdk-<provider>-0.1.0.tgz" \
   --access public \
   --provenance=false
 ```

packages/cli/README.md

@@ -30,13 +30,14 @@ provider accounts. It sends messages and performs supported provider mutations,
 start a webhook server or create a tunnel.
 
 Create an ignored repository-root `.env.cli-test` file with the credentials and dedicated test
-recipient/assets for all three providers. It must explicitly opt in:
+recipient/assets for all four providers. It must explicitly opt in:
 
 ```dotenv
 IMESSAGE_CLI_RUN_LIVE=1
 
 BLOOIO_API_KEY=
 BLOOIO_FROM_NUMBER=
+COMMS_API_KEY=
 IMESSAGE_CLI_TEST_RECIPIENT=
 IMESSAGE_CLI_TEST_IMAGE_URL=
 IMESSAGE_CLI_TEST_VIDEO_URL=
@@ -78,6 +79,7 @@ Every provider published from `packages/providers/*` is bundled with the CLI:
 
 ```text
 blooio
+comms
 photon
 sendblue
 ```
@@ -147,6 +149,7 @@ imessage-cli send \
 Current provider restrictions still apply:
 
 - Blooio requires public attachment URLs.
+- Comms currently supports plain-text messages only.
 - Photon accepts URLs and local files.
 - Sendblue accepts one URL or local file per message.
 - Group messaging remains disabled for the current official provider configurations.

packages/cli/package.json

@@ -51,6 +51,7 @@
   "dependencies": {
     "@hono/node-server": "^2.0.10",
     "@imessage-sdk/blooio": "workspace:^",
+    "@imessage-sdk/comms": "workspace:^",
     "@imessage-sdk/photon": "workspace:^",
     "@imessage-sdk/sendblue": "workspace:^",
     "@inquirer/prompts": "^8.5.2",

packages/cli/src/commands/provider-options-command.ts

@@ -6,14 +6,16 @@ import { BaseCommand } from './base-command.js';
 
 export abstract class ProviderOptionsCommand extends BaseCommand {
   provider = Option.String('--provider', {
-    description: 'Use Blooio, Photon, or Sendblue (and its configured default connection).',
+    description: 'Use Blooio, Comms, Photon, or Sendblue (and its configured default connection).',
   });
 
   noInput = Option.Boolean('--no-input', false, {
     description: 'Never prompt for missing credentials or settings.',
   });
 
-  apiKey = Option.String('--api-key', { description: 'One-time Blooio or Sendblue API key.' });
+  apiKey = Option.String('--api-key', {
+    description: 'One-time Blooio, Comms, or Sendblue API key.',
+  });
   apiSecret = Option.String('--api-secret', { description: 'One-time Sendblue API secret.' });
   projectId = Option.String('--project-id', { description: 'One-time Photon project ID.' });
   projectSecret = Option.String('--project-secret', {

packages/cli/src/config.ts

@@ -54,6 +54,7 @@ const ConnectionConfigSchema = z
 const DefaultConnectionsSchema = z
   .object({
     blooio: ConnectionNameSchema.optional(),
+    comms: ConnectionNameSchema.optional(),
     photon: ConnectionNameSchema.optional(),
     sendblue: ConnectionNameSchema.optional(),
   })

packages/cli/src/help.ts

@@ -1,7 +1,7 @@
 export function rootHelp(): string {
   return `Usage: imessage-cli <command> [options]
 
-Send and interact with iMessage through Blooio, Photon, or Sendblue.
+Send and interact with iMessage through Blooio, Comms, Photon, or Sendblue.
 
 Options:
   -V, -v, --version            output the version number

packages/cli/src/provider-names.ts

@@ -1,3 +1,3 @@
-export const BUILT_IN_PROVIDER_NAMES = ['blooio', 'photon', 'sendblue'] as const;
+export const BUILT_IN_PROVIDER_NAMES = ['blooio', 'comms', 'photon', 'sendblue'] as const;
 
 export type BuiltInProviderName = (typeof BUILT_IN_PROVIDER_NAMES)[number];

packages/cli/src/providers.ts

@@ -1,8 +1,10 @@
 import type { BlooioProvider } from '@imessage-sdk/blooio';
+import type { CommsProvider } from '@imessage-sdk/comms';
 import type { PhotonProvider } from '@imessage-sdk/photon';
 import type { SendblueProvider } from '@imessage-sdk/sendblue';
 import type { AnyIMessageProvider, IMessageCapabilities } from 'imessage-sdk';
 import { blooio, BLOOIO_CAPABILITIES } from '@imessage-sdk/blooio';
+import { comms, COMMS_CAPABILITIES } from '@imessage-sdk/comms';
 import { photon, PHOTON_CAPABILITIES } from '@imessage-sdk/photon';
 import { sendblue, SENDBLUE_CAPABILITIES } from '@imessage-sdk/sendblue';
 import { IMessageSDKError, ValidationError } from 'imessage-sdk';
@@ -47,6 +49,7 @@ export interface ProviderDoctorResult {
 
 interface BuiltInProviderMap {
   readonly blooio: BlooioProvider;
+  readonly comms: CommsProvider;
   readonly photon: PhotonProvider;
   readonly sendblue: SendblueProvider<false> | SendblueProvider<true>;
 }
@@ -158,6 +161,16 @@ function createPhoton(values: ProviderValues): PhotonProvider {
   });
 }
 
+function createComms(values: ProviderValues): CommsProvider {
+  const apiKey = optionalString('comms', values, 'apiKey');
+  const baseUrl = optionalString('comms', values, 'baseUrl');
+
+  return comms({
+    ...(apiKey === undefined ? {} : { apiKey }),
+    ...(baseUrl === undefined ? {} : { baseUrl }),
+  });
+}
+
 function createSendblue(values: ProviderValues): SendblueProvider<false> | SendblueProvider<true> {
   const apiKey = optionalString('sendblue', values, 'apiKey');
   const apiSecret = optionalString('sendblue', values, 'apiSecret');
@@ -272,6 +285,23 @@ async function doctorPhoton(values: ProviderValues): Promise<ProviderDoctorResul
   }
 }
 
+async function doctorComms(values: ProviderValues): Promise<ProviderDoctorResult> {
+  try {
+    const provider = createComms(values);
+    const messages = await provider.messages.list({
+      since: new Date(0),
+      limit: 1,
+    });
+    return {
+      status: 'ok',
+      message: 'Comms credentials and read access were verified.',
+      details: { sampledMessageCount: messages.length },
+    };
+  } catch (error) {
+    return doctorError(error, values, ['apiKey']);
+  }
+}
+
 async function doctorSendblue(values: ProviderValues): Promise<ProviderDoctorResult> {
   try {
     createSendblue(values);
@@ -350,6 +380,32 @@ export const providerRegistry: ProviderRegistry = {
     create: createBlooio,
     doctor: doctorBlooio,
   },
+  comms: {
+    name: 'comms',
+    displayName: 'Comms by Osis',
+    packageName: '@imessage-sdk/comms',
+    description: 'Comms hosted iMessage and SMS API by Osis.',
+    capabilities: COMMS_CAPABILITIES,
+    fields: [
+      {
+        key: 'apiKey',
+        label: 'API key',
+        kind: 'secret',
+        env: 'COMMS_API_KEY',
+        requiredFor: ['api', 'doctor'],
+        description: 'Bearer credential for Comms API operations.',
+      },
+      {
+        key: 'baseUrl',
+        label: 'API base URL',
+        kind: 'setting',
+        requiredFor: [],
+        description: 'Trusted Comms API endpoint override.',
+      },
+    ],
+    create: createComms,
+    doctor: doctorComms,
+  },
   photon: {
     name: 'photon',
     displayName: 'Photon Cloud',

packages/cli/src/runtime.ts

@@ -133,6 +133,8 @@ export function providerValuesFromOverrides(
   switch (provider) {
     case 'blooio':
       return { ...shared, sender: overrides.fromNumber };
+    case 'comms':
+      return shared;
     case 'photon':
       return {
         projectId: overrides.projectId,

packages/cli/test/cli.integration.test.ts

@@ -14,6 +14,7 @@ const PROVIDER_CREDENTIAL_ENVIRONMENT_VARIABLES = [
   'BLOOIO_API_KEY',
   'BLOOIO_FROM_NUMBER',
   'BLOOIO_WEBHOOK_SECRET',
+  'COMMS_API_KEY',
   'PHOTON_PROJECT_ID',
   'PHOTON_PROJECT_SECRET',
   'PHOTON_PHONE_NUMBER',
@@ -40,6 +41,7 @@ interface SentMessage {
 const secretValues = [
   process.env['BLOOIO_API_KEY'],
   process.env['BLOOIO_WEBHOOK_SECRET'],
+  process.env['COMMS_API_KEY'],
   process.env['PHOTON_PROJECT_SECRET'],
   process.env['PHOTON_WEBHOOK_SECRET'],
   process.env['SENDBLUE_API_KEY'],
@@ -130,6 +132,15 @@ describe.skipIf(!enabled)('imessage-cli live provider API', () => {
     await testCommonInteractions('photon', text);
   }, 180_000);
 
+  it('exercises Comms through the built CLI', async () => {
+    const recipient = required('IMESSAGE_CLI_TEST_RECIPIENT');
+    const conversation = await openConversation('comms', recipient);
+    const text = await sendText('comms', conversation, 'Comms text');
+
+    expect(text.providerMessageId).toBeTruthy();
+    expect(text.conversationId).toBeTruthy();
+  }, 60_000);
+
   it('exercises Sendblue through the built CLI', async () => {
     const recipient = required('IMESSAGE_CLI_TEST_RECIPIENT');
     const imageUrl = required('IMESSAGE_CLI_TEST_IMAGE_URL');
@@ -205,7 +216,10 @@ describe.skipIf(!enabled)('imessage-cli live provider API', () => {
   }, 180_000);
 });
 
-async function openConversation(provider: 'blooio' | 'photon' | 'sendblue', recipient: string) {
+async function openConversation(
+  provider: 'blooio' | 'comms' | 'photon' | 'sendblue',
+  recipient: string,
+) {
   const result = await command([
     'conversation',
     'open',
@@ -220,7 +234,7 @@ async function openConversation(provider: 'blooio' | 'photon' | 'sendblue', reci
 }
 
 async function sendText(
-  provider: 'blooio' | 'photon' | 'sendblue',
+  provider: 'blooio' | 'comms' | 'photon' | 'sendblue',
   conversation: string,
   label: string,
 ): Promise<SentMessage> {

packages/cli/test/cli.test.ts

@@ -168,7 +168,7 @@ describe('imessage-cli', () => {
       schemaVersion: 1,
       ok: true,
       command: 'provider.list',
-      data: [{ name: 'blooio' }, { name: 'photon' }, { name: 'sendblue' }],
+      data: [{ name: 'blooio' }, { name: 'comms' }, { name: 'photon' }, { name: 'sendblue' }],
     });
     expect(test.stderr.text()).toBe('');
   });

packages/cli/test/providers.test.ts

@@ -56,6 +56,7 @@ describe('built-in provider registry', () => {
     };
 
     expect(requiredWebhookFields('blooio')).toEqual(['webhookSecret']);
+    expect(requiredWebhookFields('comms')).toEqual([]);
     expect(requiredWebhookFields('photon')).toEqual(['webhookSecret']);
     expect(requiredWebhookFields('sendblue')).toEqual(['fromNumber', 'webhookSecret']);
   });
@@ -73,6 +74,9 @@ describe('built-in provider registry', () => {
       projectSecret: 'project-secret',
       phone: '+15550000002',
     });
+    const comms = createProvider('comms', {
+      apiKey: 'comms-key',
+    });
     const sendblue = createProvider('sendblue', {
       apiKey: 'sendblue-key',
       apiSecret: 'sendblue-secret',
@@ -81,6 +85,7 @@ describe('built-in provider registry', () => {
     });
 
     expect(blooio.name).toBe('blooio');
+    expect(comms.name).toBe('comms');
     expect(photon.name).toBe('photon');
     expect(sendblue.name).toBe('sendblue');
     expect(sendblue.capabilities.conversations.markRead).toBe(true);
@@ -160,6 +165,36 @@ describe('built-in provider registry', () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
+  it('verifies Comms credentials through a non-mutating message lookup', async () => {
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+      void input;
+      void init;
+      return new Response(JSON.stringify({ messages: [] }), {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+      });
+    });
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await providerRegistry.comms.doctor({
+      apiKey: 'comms-key',
+      baseUrl: 'https://comms.test/api/v1/comms',
+    });
+
+    expect(result).toMatchObject({
+      status: 'ok',
+      details: { sampledMessageCount: 0 },
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      'https://comms.test/api/v1/comms/messages?since=1970-01-01T00%3A00%3A00.000Z&limit=1',
+      expect.objectContaining({
+        headers: expect.any(Headers),
+      }),
+    );
+    const headers = new Headers(fetchMock.mock.calls[0]?.[1]?.headers);
+    expect(headers.get('authorization')).toBe('Bearer comms-key');
+  });
+
   it('returns safe doctor failures without exposing secret values', async () => {
     const secret = 'blooio-secret-value';
     vi.stubGlobal(