spectrum-ts 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -24,6 +24,11 @@
       "types": "./dist/providers/terminal/index.d.ts",
       "bun": "./src/providers/terminal/index.ts",
       "default": "./dist/providers/terminal/index.js"
+    },
+    "./providers/whatsapp-business": {
+      "types": "./dist/providers/whatsapp-business/index.d.ts",
+      "bun": "./src/providers/whatsapp-business/index.ts",
+      "default": "./dist/providers/whatsapp-business/index.js"
     }
   },
   "scripts": {
@@ -32,6 +37,7 @@
   },
   "dependencies": {
     "@photon-ai/advanced-imessage": "^0.1.0",
+    "@photon-ai/whatsapp-business": "^0.1.1",
     "@photon-ai/imessage-kit": "^2.1.2",
     "@repeaterjs/repeater": "^3.0.6",
     "better-grpc": "^0.3.2",

package/src/index.ts

@@ -23,4 +23,16 @@ export {
 export type { Message } from "./types/message";
 export type { Space } from "./types/space";
 export type { User } from "./types/user";
+export type {
+  CloudPlatform,
+  DedicatedTokenData,
+  ImessageInfoData,
+  PlatformStatus,
+  PlatformsData,
+  SharedTokenData,
+  SubscriptionData,
+  SubscriptionStatus,
+  TokenData,
+} from "./utils/cloud";
+export { cloud, SpectrumCloudError } from "./utils/cloud";
 export { type ManagedStream, mergeStreams, stream } from "./utils/stream";

package/src/platform/define.ts

@@ -289,14 +289,13 @@ export function definePlatform<
     throw new Error("Invalid input to platform narrowing function");
   }) as Platform<Def>;
 
-  narrower.config = (
-    config: z.input<_ConfigSchema> = {} as z.input<_ConfigSchema>
-  ) => {
+  narrower.config = (config?: z.input<_ConfigSchema>) => {
+    const resolvedConfig = config ?? {};
     return {
       __tag: "PlatformProviderConfig" as const,
       __def: undefined as unknown as Def,
       __name: name,
-      config,
+      config: resolvedConfig,
       __definition: fullDef as AnyPlatformDef,
     } satisfies PlatformProviderConfig<Def> as PlatformProviderConfig<Def>;
   };

package/src/platform/types.ts

@@ -140,8 +140,8 @@ export interface PlatformDef<
   lifecycle: {
     createClient: (ctx: {
       config: z.infer<_ConfigSchema>;
-      projectId: string;
-      projectSecret: string;
+      projectId: string | undefined;
+      projectSecret: string | undefined;
     }) => Promise<_Client>;
     destroyClient: (ctx: { client: _Client }) => Promise<void>;
   };
@@ -423,7 +423,11 @@ export interface SpectrumLike<
 // ---------------------------------------------------------------------------
 
 export interface Platform<Def extends AnyPlatformDef> {
-  config(config?: z.input<Def["config"]>): PlatformProviderConfig<Def>;
+  config(
+    ...args: Record<string, never> extends z.input<Def["config"]>
+      ? [config?: z.input<Def["config"]>]
+      : [config: z.input<Def["config"]>]
+  ): PlatformProviderConfig<Def>;
   <Providers extends PlatformProviderConfig[]>(
     spectrum: SpectrumLike<Providers>
   ): HasProvider<Providers, Def["name"]> extends true

package/src/providers/imessage/auth.ts

@@ -2,73 +2,27 @@ import {
   type AdvancedIMessage,
   createClient,
 } from "@photon-ai/advanced-imessage";
-import { SPECTRUM_CLOUD_URL } from "../../utils/cloud";
+import {
+  cloud,
+  type DedicatedTokenData,
+  type SharedTokenData,
+} from "../../utils/cloud";
 
 const RENEWAL_RATIO = 0.8;
 const EXPIRY_BUFFER_MS = 30_000;
 const RETRY_DELAY_MS = 30_000;
 
-interface SharedTokenData {
-  expiresIn: number;
-  token: string;
-  type: "shared";
-}
-
-interface DedicatedTokenData {
-  auth: Record<string, string>;
-  expiresIn: number;
-  type: "dedicated";
-}
-
-type TokenData = SharedTokenData | DedicatedTokenData;
-
-interface TokenResponse {
-  data: TokenData;
-  succeed: boolean;
-}
-
 interface CloudAuth {
   dispose: () => void;
 }
 
 const cloudAuthState = new WeakMap<AdvancedIMessage[], CloudAuth>();
 
-async function fetchTokens(
-  projectId: string,
-  projectSecret: string
-): Promise<TokenData> {
-  const url = `${SPECTRUM_CLOUD_URL}/${projectId}/imessage/tokens`;
-  const credentials = btoa(`${projectId}:${projectSecret}`);
-
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      Authorization: `Basic ${credentials}`,
-    },
-  });
-
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `Spectrum Cloud authentication failed (${response.status}): ${body || response.statusText}`
-    );
-  }
-
-  const json = (await response.json()) as TokenResponse;
-  if (!json.succeed) {
-    throw new Error(
-      "Spectrum Cloud authentication failed: server returned succeed=false"
-    );
-  }
-
-  return json.data;
-}
-
 export async function createCloudClients(
   projectId: string,
   projectSecret: string
 ): Promise<AdvancedIMessage[]> {
-  let tokenData = await fetchTokens(projectId, projectSecret);
+  let tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
   let tokenExpiresAt = Date.now() + tokenData.expiresIn * 1000;
   let disposed = false;
   let renewalTimer: ReturnType<typeof setTimeout> | undefined;
@@ -82,7 +36,7 @@ export async function createCloudClients(
 
     renewalTimer = setTimeout(async () => {
       try {
-        tokenData = await fetchTokens(projectId, projectSecret);
+        tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
         tokenExpiresAt = Date.now() + tokenData.expiresIn * 1000;
         scheduleRenewal();
       } catch {
@@ -99,7 +53,7 @@ export async function createCloudClients(
     if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) {
       return;
     }
-    tokenData = await fetchTokens(projectId, projectSecret);
+    tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
     tokenExpiresAt = Date.now() + tokenData.expiresIn * 1000;
     scheduleRenewal();
   };

package/src/providers/imessage/index.ts

@@ -87,6 +87,14 @@ export const imessage = definePlatform("iMessage", {
         );
       }
 
+      if (!(projectId && projectSecret)) {
+        throw new Error(
+          "iMessage requires projectId and projectSecret. " +
+            "Either pass credentials to Spectrum(), use local mode: imessage.config({ local: true }), " +
+            "or provide explicit client config: imessage.config({ clients: [...] })"
+        );
+      }
+
       return await createCloudClients(projectId, projectSecret);
     },
 

package/src/providers/whatsapp-business/index.ts

@@ -0,0 +1,77 @@
+import {
+  createClient,
+  type WhatsAppClient,
+} from "@photon-ai/whatsapp-business";
+import { definePlatform } from "../../platform/define";
+import { messages, reactToMessage, replyToMessage, send } from "./messages";
+import { configSchema, spaceSchema } from "./types";
+
+export const whatsappBusiness = definePlatform("WhatsApp Business", {
+  config: configSchema,
+
+  user: {
+    resolve: async ({ input }) => ({ id: input.userID }),
+  },
+
+  space: {
+    schema: spaceSchema,
+    resolve: async ({ input }) => {
+      if (input.users.length === 0) {
+        throw new Error("WhatsApp space creation requires at least one user");
+      }
+      if (input.users.length > 1) {
+        throw new Error(
+          "WhatsApp Business API only supports 1:1 conversations"
+        );
+      }
+      const user = input.users[0];
+      if (!user) {
+        throw new Error("WhatsApp space creation requires a user");
+      }
+      return { id: user.id };
+    },
+  },
+
+  lifecycle: {
+    createClient: async ({ config }): Promise<WhatsAppClient> => {
+      return createClient({
+        accessToken: config.accessToken,
+        phoneNumberId: config.phoneNumberId,
+        appSecret: config.appSecret ?? "",
+      });
+    },
+
+    destroyClient: async ({ client }: { client: WhatsAppClient }) => {
+      await client.close();
+    },
+  },
+
+  events: {
+    messages: ({ client }) => messages(client as WhatsAppClient),
+  },
+
+  actions: {
+    send: async ({ space, content, client }) => {
+      const wa = client as WhatsAppClient;
+      for (const item of content) {
+        await send(wa, space.id, item);
+      }
+    },
+
+    reactToMessage: async ({ space, messageId, reaction, client }) => {
+      await reactToMessage(
+        client as WhatsAppClient,
+        space.id,
+        messageId,
+        reaction
+      );
+    },
+
+    replyToMessage: async ({ space, messageId, content, client }) => {
+      const wa = client as WhatsAppClient;
+      for (const item of content) {
+        await replyToMessage(wa, space.id, messageId, item);
+      }
+    },
+  },
+});

package/src/providers/whatsapp-business/messages.ts

@@ -0,0 +1,240 @@
+import type {
+  InboundMessage,
+  WhatsAppClient,
+} from "@photon-ai/whatsapp-business";
+import type { Content } from "../../types/content";
+import { type ManagedStream, stream } from "../../utils/stream";
+import type { WhatsAppMessage } from "./types";
+
+const toMessage = async (
+  client: WhatsAppClient,
+  msg: InboundMessage
+): Promise<WhatsAppMessage> => {
+  const content = await mapContent(client, msg.content);
+  return {
+    id: msg.id,
+    content,
+    sender: { id: msg.from },
+    space: { id: msg.from },
+    timestamp: msg.timestamp,
+  };
+};
+
+const mapContent = async (
+  client: WhatsAppClient,
+  content: InboundMessage["content"]
+): Promise<Content[]> => {
+  switch (content.type) {
+    case "text":
+      return [{ type: "plain_text", text: content.body }];
+    case "image":
+    case "video":
+    case "audio":
+    case "document":
+      return [await downloadMedia(client, content.media)];
+    case "sticker":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "sticker", ...content.sticker },
+        },
+      ];
+    case "location":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "location", ...content.location },
+        },
+      ];
+    case "contacts":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "contacts", contacts: content.contacts },
+        },
+      ];
+    case "reaction":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "reaction", ...content.reaction },
+        },
+      ];
+    case "interactive":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "interactive", ...content.interactive },
+        },
+      ];
+    case "button":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "button", ...content.button },
+        },
+      ];
+    case "order":
+      return [
+        { type: "custom", raw: { whatsapp_type: "order", ...content.order } },
+      ];
+    case "system":
+      return [
+        {
+          type: "custom",
+          raw: { whatsapp_type: "system", ...content.system },
+        },
+      ];
+    default:
+      return [{ type: "custom", raw: { whatsapp_type: "unknown" } }];
+  }
+};
+
+const downloadMedia = async (
+  client: WhatsAppClient,
+  media: { id: string; mimeType: string; filename?: string }
+): Promise<Content> => {
+  try {
+    const { url } = await client.media.getUrl(media.id);
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Media download failed: ${response.status}`);
+    }
+    const data = Buffer.from(await response.arrayBuffer());
+    return {
+      type: "attachment",
+      data,
+      mimeType: media.mimeType,
+      name: media.filename ?? `media-${media.id}`,
+    };
+  } catch {
+    return {
+      type: "custom",
+      raw: {
+        whatsapp_type: "media_error",
+        mediaId: media.id,
+        mimeType: media.mimeType,
+      },
+    };
+  }
+};
+
+const mimeToMediaType = (
+  mimeType: string
+): "image" | "video" | "audio" | "document" => {
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.startsWith("video/")) {
+    return "video";
+  }
+  if (mimeType.startsWith("audio/")) {
+    return "audio";
+  }
+  return "document";
+};
+
+export const messages = (
+  client: WhatsAppClient
+): ManagedStream<WhatsAppMessage> => {
+  const eventStream = client.events
+    .subscribe()
+    .filter(
+      (e): e is Extract<typeof e, { type: "message" }> => e.type === "message"
+    );
+
+  return stream<WhatsAppMessage>((emit, end) => {
+    (async () => {
+      try {
+        for await (const event of eventStream) {
+          const msg = await toMessage(client, event.message);
+          emit(msg);
+        }
+        end();
+      } catch (e) {
+        end(e);
+      }
+    })();
+    return () => eventStream.close();
+  });
+};
+
+export const send = async (
+  client: WhatsAppClient,
+  spaceId: string,
+  content: Content
+): Promise<void> => {
+  switch (content.type) {
+    case "plain_text":
+      await client.messages.send({ to: spaceId, text: content.text });
+      break;
+    case "attachment": {
+      const { mediaId } = await client.media.upload({
+        file: content.data,
+        mimeType: content.mimeType,
+        filename: content.name,
+      });
+      const mediaType = mimeToMediaType(content.mimeType);
+      const mediaPayload =
+        mediaType === "document"
+          ? { id: mediaId, filename: content.name }
+          : { id: mediaId };
+      await client.messages.send({
+        to: spaceId,
+        [mediaType]: mediaPayload,
+      } as Parameters<typeof client.messages.send>[0]);
+      break;
+    }
+    default:
+      break;
+  }
+};
+
+export const reactToMessage = async (
+  client: WhatsAppClient,
+  spaceId: string,
+  messageId: string,
+  reaction: string
+): Promise<void> => {
+  await client.messages.send({
+    to: spaceId,
+    reaction: { messageId, emoji: reaction },
+  });
+};
+
+export const replyToMessage = async (
+  client: WhatsAppClient,
+  spaceId: string,
+  messageId: string,
+  content: Content
+): Promise<void> => {
+  switch (content.type) {
+    case "plain_text":
+      await client.messages.send({
+        to: spaceId,
+        replyTo: messageId,
+        text: content.text,
+      });
+      break;
+    case "attachment": {
+      const { mediaId } = await client.media.upload({
+        file: content.data,
+        mimeType: content.mimeType,
+        filename: content.name,
+      });
+      const mediaType = mimeToMediaType(content.mimeType);
+      const mediaPayload =
+        mediaType === "document"
+          ? { id: mediaId, filename: content.name }
+          : { id: mediaId };
+      await client.messages.send({
+        to: spaceId,
+        replyTo: messageId,
+        [mediaType]: mediaPayload,
+      } as Parameters<typeof client.messages.send>[0]);
+      break;
+    }
+    default:
+      break;
+  }
+};

package/src/providers/whatsapp-business/types.ts

@@ -0,0 +1,19 @@
+import z from "zod";
+import type { SchemaMessage } from "../../platform/types";
+
+export const configSchema = z.object({
+  accessToken: z.string().min(1),
+  phoneNumberId: z.string().min(1),
+  appSecret: z.string().optional(),
+});
+
+export const userSchema = z.object({});
+
+export const spaceSchema = z.object({
+  id: z.string(),
+});
+
+export type WhatsAppMessage = SchemaMessage<
+  typeof userSchema,
+  typeof spaceSchema
+>;

package/src/spectrum.ts

@@ -47,11 +47,18 @@ export type SpectrumInstance<
 // Config validation
 // ---------------------------------------------------------------------------
 
-const spectrumConfigSchema = z.object({
-  projectId: z.string().min(1),
-  projectSecret: z.string().min(1),
-  providers: z.array(z.custom<PlatformProviderConfig>()),
-});
+const spectrumConfigSchema = z.union([
+  z.object({
+    projectId: z.string().min(1),
+    projectSecret: z.string().min(1),
+    providers: z.array(z.custom<PlatformProviderConfig>()),
+  }),
+  z.object({
+    projectId: z.undefined().optional(),
+    projectSecret: z.undefined().optional(),
+    providers: z.array(z.custom<PlatformProviderConfig>()),
+  }),
+]);
 
 // ---------------------------------------------------------------------------
 // Spectrum() factory
@@ -60,15 +67,21 @@ const spectrumConfigSchema = z.object({
 export async function Spectrum<
   const Providers extends PlatformProviderConfig[],
 >(
-  projectId: string,
-  projectSecret: string,
-  options: { providers: [...Providers] }
+  options:
+    | {
+        projectId: string;
+        projectSecret: string;
+        providers: [...Providers];
+      }
+    | {
+        projectId?: never;
+        projectSecret?: never;
+        providers: [...Providers];
+      }
 ): Promise<SpectrumInstance<Providers>> {
-  spectrumConfigSchema.parse({
-    projectId,
-    projectSecret,
-    providers: options.providers,
-  });
+  spectrumConfigSchema.parse(options);
+
+  const { projectId, projectSecret, providers } = options;
 
   const platformStates = new Map<
     string,
@@ -81,7 +94,7 @@ export async function Spectrum<
   let stopped = false;
 
   // Initialize all provider clients eagerly
-  for (const provider of options.providers) {
+  for (const provider of providers) {
     const providerConfig = provider as PlatformProviderConfig;
     const def = providerConfig.__definition;
     const userConfig = def.config.parse(providerConfig.config);
@@ -344,7 +357,7 @@ export async function Spectrum<
   );
 
   const base = {
-    __providers: options.providers,
+    __providers: providers,
     __internal: { platforms: platformStates },
     messages,
     stop: stopOnce,