spectrum-ts 0.1.2 → 0.2.0

package/dist/{chunk-UZ2CXPOD.js → chunk-LIRM7SBA.js}

@@ -155,12 +155,13 @@ function definePlatform(name, def) {
     }
     throw new Error("Invalid input to platform narrowing function");
   });
-  narrower.config = (config = {}) => {
+  narrower.config = (config) => {
+    const resolvedConfig = config ?? {};
     return {
       __tag: "PlatformProviderConfig",
       __def: void 0,
       __name: name,
-      config,
+      config: resolvedConfig,
       __definition: fullDef
     };
   };

package/dist/chunk-XOBTWTFC.js

@@ -0,0 +1,67 @@
+// src/utils/cloud.ts
+var SPECTRUM_CLOUD_URL = `https://${process.env.SPECTRUM_CLOUD_URL ?? "spectrum-cloud.photon.codes"}`;
+var SpectrumCloudError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.name = "SpectrumCloudError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var request = async (path, init) => {
+  const response = await fetch(`${SPECTRUM_CLOUD_URL}${path}`, init);
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    try {
+      const parsed = JSON.parse(body);
+      throw new SpectrumCloudError(
+        response.status,
+        parsed.code,
+        parsed.message
+      );
+    } catch (error) {
+      if (error instanceof SpectrumCloudError) {
+        throw error;
+      }
+      throw new SpectrumCloudError(
+        response.status,
+        "UNKNOWN",
+        body || response.statusText
+      );
+    }
+  }
+  const json = await response.json();
+  if (!json.succeed) {
+    throw new SpectrumCloudError(
+      response.status,
+      "UNKNOWN",
+      "Server returned succeed=false"
+    );
+  }
+  return json.data;
+};
+var basicAuth = (projectId, projectSecret) => `Basic ${btoa(`${projectId}:${projectSecret}`)}`;
+var cloud = {
+  getSubscription: (projectId) => request(`/projects/${projectId}/billing/subscription`),
+  issueImessageTokens: (projectId, projectSecret) => request(`/projects/${projectId}/imessage/tokens`, {
+    method: "POST",
+    headers: { Authorization: basicAuth(projectId, projectSecret) }
+  }),
+  getImessageInfo: (projectId) => request(`/projects/${projectId}/imessage/`),
+  getPlatforms: (projectId) => request(`/projects/${projectId}/platforms/`),
+  togglePlatform: (projectId, projectSecret, platform, enabled) => request(`/projects/${projectId}/platforms/`, {
+    method: "PATCH",
+    headers: {
+      Authorization: basicAuth(projectId, projectSecret),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ platform, enabled })
+  })
+};
+
+export {
+  SpectrumCloudError,
+  cloud
+};

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import z__default from 'zod';
-import { P as ProviderMessage, a as PlatformDef, b as Platform, c as PlatformProviderConfig, S as SpectrumLike, C as CustomEventStreams, d as Space, M as Message, e as ContentBuilder } from './types-eXHZpal1.js';
-export { A as AnyPlatformDef, f as Content, E as EventProducer, g as PlatformInstance, h as PlatformMessage, i as PlatformSpace, j as PlatformUser, k as SchemaMessage, U as User, l as attachment, m as custom, t as text } from './types-eXHZpal1.js';
+import { P as ProviderMessage, a as PlatformDef, b as Platform, c as PlatformProviderConfig, S as SpectrumLike, C as CustomEventStreams, d as Space, M as Message, e as ContentBuilder } from './types-DQE0dQT4.js';
+export { A as AnyPlatformDef, f as Content, E as EventProducer, g as PlatformInstance, h as PlatformMessage, i as PlatformSpace, j as PlatformUser, k as SchemaMessage, U as User, l as attachment, m as custom, t as text } from './types-DQE0dQT4.js';
 export { M as ManagedStream, m as mergeStreams, s as stream } from './stream-DGy4geUK.js';
 import 'hotscript';
 import 'type-fest';
@@ -39,4 +39,41 @@ declare function Spectrum<const Providers extends PlatformProviderConfig[]>(opti
     providers: [...Providers];
 }): Promise<SpectrumInstance<Providers>>;
 
-export { ContentBuilder, Message, Platform, PlatformDef, PlatformProviderConfig, Space, Spectrum, type SpectrumInstance, definePlatform };
+type SubscriptionStatus = "active" | "canceled" | "past_due";
+interface SubscriptionData {
+    status: SubscriptionStatus | null;
+    tier: string;
+}
+interface SharedTokenData {
+    expiresIn: number;
+    token: string;
+    type: "shared";
+}
+interface DedicatedTokenData {
+    auth: Record<string, string>;
+    expiresIn: number;
+    type: "dedicated";
+}
+type TokenData = SharedTokenData | DedicatedTokenData;
+type CloudPlatform = "imessage" | "whatsapp_business";
+interface PlatformStatus {
+    enabled: boolean;
+}
+type PlatformsData = Record<CloudPlatform, PlatformStatus>;
+interface ImessageInfoData {
+    type: "shared" | "dedicated";
+}
+declare class SpectrumCloudError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare const cloud: {
+    getSubscription: (projectId: string) => Promise<SubscriptionData>;
+    issueImessageTokens: (projectId: string, projectSecret: string) => Promise<TokenData>;
+    getImessageInfo: (projectId: string) => Promise<ImessageInfoData>;
+    getPlatforms: (projectId: string) => Promise<PlatformsData>;
+    togglePlatform: (projectId: string, projectSecret: string, platform: CloudPlatform, enabled: boolean) => Promise<PlatformsData>;
+};
+
+export { type CloudPlatform, ContentBuilder, type DedicatedTokenData, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, type SharedTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, cloud, definePlatform };

package/dist/index.js

@@ -1,10 +1,14 @@
+import {
+  SpectrumCloudError,
+  cloud
+} from "./chunk-XOBTWTFC.js";
 import {
   mergeStreams,
   stream
 } from "./chunk-3TBRO2J7.js";
 import {
   definePlatform
-} from "./chunk-UZ2CXPOD.js";
+} from "./chunk-LIRM7SBA.js";
 
 // src/spectrum.ts
 import z from "zod";
@@ -339,7 +343,9 @@ function attachment(input, options) {
 }
 export {
   Spectrum,
+  SpectrumCloudError,
   attachment,
+  cloud,
   custom,
   definePlatform,
   mergeStreams,

package/dist/providers/imessage/index.d.ts

@@ -3,7 +3,7 @@ import { AdvancedIMessage } from '@photon-ai/advanced-imessage';
 import { IMessageSDK } from '@photon-ai/imessage-kit';
 import * as z from 'zod';
 import z__default from 'zod';
-import { k as SchemaMessage, b as Platform, a as PlatformDef, P as ProviderMessage } from '../../types-eXHZpal1.js';
+import { k as SchemaMessage, b as Platform, a as PlatformDef, P as ProviderMessage } from '../../types-DQE0dQT4.js';
 import * as zod_v4_core from 'zod/v4/core';
 import 'hotscript';
 import 'type-fest';

package/dist/providers/imessage/index.js

@@ -1,10 +1,13 @@
+import {
+  cloud
+} from "../../chunk-XOBTWTFC.js";
 import {
   mergeStreams,
   stream
 } from "../../chunk-3TBRO2J7.js";
 import {
   definePlatform
-} from "../../chunk-UZ2CXPOD.js";
+} from "../../chunk-LIRM7SBA.js";
 
 // src/providers/imessage/index.ts
 import { createClient as createClient2, directChat } from "@photon-ai/advanced-imessage";
@@ -14,40 +17,12 @@ import { IMessageSDK as IMessageSDK2 } from "@photon-ai/imessage-kit";
 import {
   createClient
 } from "@photon-ai/advanced-imessage";
-
-// src/utils/cloud.ts
-var SPECTRUM_CLOUD_URL = `https://${process.env.SPECTRUM_CLOUD_URL ?? "spectrum-cloud.photon.codes"}`;
-
-// src/providers/imessage/auth.ts
 var RENEWAL_RATIO = 0.8;
 var EXPIRY_BUFFER_MS = 3e4;
 var RETRY_DELAY_MS = 3e4;
 var cloudAuthState = /* @__PURE__ */ new WeakMap();
-async function fetchTokens(projectId, projectSecret) {
-  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();
-  if (!json.succeed) {
-    throw new Error(
-      "Spectrum Cloud authentication failed: server returned succeed=false"
-    );
-  }
-  return json.data;
-}
 async function createCloudClients(projectId, projectSecret) {
-  let tokenData = await fetchTokens(projectId, projectSecret);
+  let tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
   let tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
   let disposed = false;
   let renewalTimer;
@@ -59,7 +34,7 @@ async function createCloudClients(projectId, projectSecret) {
     const renewInMs = Math.max(ttlMs * RENEWAL_RATIO, 5e3);
     renewalTimer = setTimeout(async () => {
       try {
-        tokenData = await fetchTokens(projectId, projectSecret);
+        tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
         tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
         scheduleRenewal();
       } catch {
@@ -74,7 +49,7 @@ async function createCloudClients(projectId, projectSecret) {
     if (Date.now() < tokenExpiresAt - EXPIRY_BUFFER_MS) {
       return;
     }
-    tokenData = await fetchTokens(projectId, projectSecret);
+    tokenData = await cloud.issueImessageTokens(projectId, projectSecret);
     tokenExpiresAt = Date.now() + tokenData.expiresIn * 1e3;
     scheduleRenewal();
   };

package/dist/providers/terminal/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Platform, a as PlatformDef, P as ProviderMessage } from '../../types-eXHZpal1.js';
+import { b as Platform, a as PlatformDef, P as ProviderMessage } from '../../types-DQE0dQT4.js';
 import * as node_readline from 'node:readline';
 import z__default from 'zod';
 import 'hotscript';

package/dist/providers/terminal/index.js

@@ -1,6 +1,6 @@
 import {
   definePlatform
-} from "../../chunk-UZ2CXPOD.js";
+} from "../../chunk-LIRM7SBA.js";
 
 // src/providers/terminal/index.ts
 import { createInterface } from "readline";

package/dist/providers/whatsapp-business/index.d.ts

@@ -0,0 +1,41 @@
+import { M as ManagedStream } from '../../stream-DGy4geUK.js';
+import * as z from 'zod';
+import z__default from 'zod';
+import { k as SchemaMessage, b as Platform, a as PlatformDef, P as ProviderMessage } from '../../types-DQE0dQT4.js';
+import * as zod_v4_core from 'zod/v4/core';
+import { WhatsAppClient } from '@photon-ai/whatsapp-business';
+import 'hotscript';
+import 'type-fest';
+
+declare const userSchema: z__default.ZodObject<{}, z__default.core.$strip>;
+declare const spaceSchema: z__default.ZodObject<{
+    id: z__default.ZodString;
+}, z__default.core.$strip>;
+type WhatsAppMessage = SchemaMessage<typeof userSchema, typeof spaceSchema>;
+
+declare const whatsappBusiness: Platform<PlatformDef<"WhatsApp Business", z.ZodObject<{
+    accessToken: z.ZodString;
+    phoneNumberId: z.ZodString;
+    appSecret: z.ZodOptional<z.ZodString>;
+}, zod_v4_core.$strip>, z.ZodType<object, unknown, zod_v4_core.$ZodTypeInternals<object, unknown>> | undefined, z.ZodObject<{
+    id: z.ZodString;
+}, zod_v4_core.$strip>, z.ZodType<object, unknown, zod_v4_core.$ZodTypeInternals<object, unknown>> | undefined, WhatsAppClient, {
+    id: string;
+}, {
+    id: string;
+}, undefined, ProviderMessage<{
+    id: string;
+}, {
+    id: string;
+}, Record<never, never>>, {
+    messages: ({ client }: {
+        client: WhatsAppClient;
+        config: {
+            accessToken: string;
+            phoneNumberId: string;
+            appSecret?: string | undefined;
+        };
+    }) => ManagedStream<WhatsAppMessage>;
+}>> & Readonly<Record<never, never>>;
+
+export { whatsappBusiness };

package/dist/providers/whatsapp-business/index.js

@@ -0,0 +1,280 @@
+import {
+  stream
+} from "../../chunk-3TBRO2J7.js";
+import {
+  definePlatform
+} from "../../chunk-LIRM7SBA.js";
+
+// src/providers/whatsapp-business/index.ts
+import {
+  createClient
+} from "@photon-ai/whatsapp-business";
+
+// src/providers/whatsapp-business/messages.ts
+var toMessage = async (client, msg) => {
+  const content = await mapContent(client, msg.content);
+  return {
+    id: msg.id,
+    content,
+    sender: { id: msg.from },
+    space: { id: msg.from },
+    timestamp: msg.timestamp
+  };
+};
+var mapContent = async (client, 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" } }];
+  }
+};
+var downloadMedia = async (client, media) => {
+  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
+      }
+    };
+  }
+};
+var mimeToMediaType = (mimeType) => {
+  if (mimeType.startsWith("image/")) {
+    return "image";
+  }
+  if (mimeType.startsWith("video/")) {
+    return "video";
+  }
+  if (mimeType.startsWith("audio/")) {
+    return "audio";
+  }
+  return "document";
+};
+var messages = (client) => {
+  const eventStream = client.events.subscribe().filter(
+    (e) => e.type === "message"
+  );
+  return stream((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();
+  });
+};
+var send = async (client, spaceId, content) => {
+  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
+      });
+      break;
+    }
+    default:
+      break;
+  }
+};
+var reactToMessage = async (client, spaceId, messageId, reaction) => {
+  await client.messages.send({
+    to: spaceId,
+    reaction: { messageId, emoji: reaction }
+  });
+};
+var replyToMessage = async (client, spaceId, messageId, content) => {
+  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
+      });
+      break;
+    }
+    default:
+      break;
+  }
+};
+
+// src/providers/whatsapp-business/types.ts
+import z from "zod";
+var configSchema = z.object({
+  accessToken: z.string().min(1),
+  phoneNumberId: z.string().min(1),
+  appSecret: z.string().optional()
+});
+var userSchema = z.object({});
+var spaceSchema = z.object({
+  id: z.string()
+});
+
+// src/providers/whatsapp-business/index.ts
+var 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 }) => {
+      return createClient({
+        accessToken: config.accessToken,
+        phoneNumberId: config.phoneNumberId,
+        appSecret: config.appSecret ?? ""
+      });
+    },
+    destroyClient: async ({ client }) => {
+      await client.close();
+    }
+  },
+  events: {
+    messages: ({ client }) => messages(client)
+  },
+  actions: {
+    send: async ({ space, content, client }) => {
+      const wa = client;
+      for (const item of content) {
+        await send(wa, space.id, item);
+      }
+    },
+    reactToMessage: async ({ space, messageId, reaction, client }) => {
+      await reactToMessage(
+        client,
+        space.id,
+        messageId,
+        reaction
+      );
+    },
+    replyToMessage: async ({ space, messageId, content, client }) => {
+      const wa = client;
+      for (const item of content) {
+        await replyToMessage(wa, space.id, messageId, item);
+      }
+    }
+  }
+});
+export {
+  whatsappBusiness
+};

package/dist/{types-eXHZpal1.d.ts → types-DQE0dQT4.d.ts}

@@ -252,7 +252,7 @@ interface SpectrumLike<Providers extends PlatformProviderConfig[] = PlatformProv
     readonly __providers: Providers;
 }
 interface Platform<Def extends AnyPlatformDef> {
-    config(config?: z__default.input<Def["config"]>): PlatformProviderConfig<Def>;
+    config(...args: Record<string, never> extends z__default.input<Def["config"]> ? [config?: z__default.input<Def["config"]>] : [config: z__default.input<Def["config"]>]): PlatformProviderConfig<Def>;
     <Providers extends PlatformProviderConfig[]>(spectrum: SpectrumLike<Providers>): HasProvider<Providers, Def["name"]> extends true ? PlatformInstance<Def> : never;
     (space: Space): PlatformSpace<Def>;
     (message: Message): PlatformMessage<Def>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "0.1.2",
+  "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

@@ -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/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/utils/cloud.ts

@@ -1 +1,147 @@
 export const SPECTRUM_CLOUD_URL = `https://${process.env.SPECTRUM_CLOUD_URL ?? "spectrum-cloud.photon.codes"}`;
+
+// ---------------------------------------------------------------------------
+// API response types (aligned with OpenAPI spec)
+// ---------------------------------------------------------------------------
+
+export type SubscriptionStatus = "active" | "canceled" | "past_due";
+
+export interface SubscriptionData {
+  status: SubscriptionStatus | null;
+  tier: string;
+}
+
+export interface SharedTokenData {
+  expiresIn: number;
+  token: string;
+  type: "shared";
+}
+
+export interface DedicatedTokenData {
+  auth: Record<string, string>;
+  expiresIn: number;
+  type: "dedicated";
+}
+
+export type TokenData = SharedTokenData | DedicatedTokenData;
+
+export type CloudPlatform = "imessage" | "whatsapp_business";
+
+export interface PlatformStatus {
+  enabled: boolean;
+}
+
+export type PlatformsData = Record<CloudPlatform, PlatformStatus>;
+
+export interface ImessageInfoData {
+  type: "shared" | "dedicated";
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class SpectrumCloudError extends Error {
+  readonly status: number;
+  readonly code: string;
+
+  constructor(status: number, code: string, message: string) {
+    super(message);
+    this.name = "SpectrumCloudError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface SuccessResponse<T> {
+  data: T;
+  succeed: true;
+}
+
+interface ErrorBody {
+  code: string;
+  message: string;
+  succeed: false;
+}
+
+const request = async <T>(path: string, init?: RequestInit): Promise<T> => {
+  const response = await fetch(`${SPECTRUM_CLOUD_URL}${path}`, init);
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    try {
+      const parsed = JSON.parse(body) as ErrorBody;
+      throw new SpectrumCloudError(
+        response.status,
+        parsed.code,
+        parsed.message
+      );
+    } catch (error) {
+      if (error instanceof SpectrumCloudError) {
+        throw error;
+      }
+      throw new SpectrumCloudError(
+        response.status,
+        "UNKNOWN",
+        body || response.statusText
+      );
+    }
+  }
+
+  const json = (await response.json()) as SuccessResponse<T>;
+  if (!json.succeed) {
+    throw new SpectrumCloudError(
+      response.status,
+      "UNKNOWN",
+      "Server returned succeed=false"
+    );
+  }
+
+  return json.data;
+};
+
+const basicAuth = (projectId: string, projectSecret: string): string =>
+  `Basic ${btoa(`${projectId}:${projectSecret}`)}`;
+
+// ---------------------------------------------------------------------------
+// Cloud API client
+// ---------------------------------------------------------------------------
+
+export const cloud = {
+  getSubscription: (projectId: string): Promise<SubscriptionData> =>
+    request(`/projects/${projectId}/billing/subscription`),
+
+  issueImessageTokens: (
+    projectId: string,
+    projectSecret: string
+  ): Promise<TokenData> =>
+    request(`/projects/${projectId}/imessage/tokens`, {
+      method: "POST",
+      headers: { Authorization: basicAuth(projectId, projectSecret) },
+    }),
+
+  getImessageInfo: (projectId: string): Promise<ImessageInfoData> =>
+    request(`/projects/${projectId}/imessage/`),
+
+  getPlatforms: (projectId: string): Promise<PlatformsData> =>
+    request(`/projects/${projectId}/platforms/`),
+
+  togglePlatform: (
+    projectId: string,
+    projectSecret: string,
+    platform: CloudPlatform,
+    enabled: boolean
+  ): Promise<PlatformsData> =>
+    request(`/projects/${projectId}/platforms/`, {
+      method: "PATCH",
+      headers: {
+        Authorization: basicAuth(projectId, projectSecret),
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ platform, enabled }),
+    }),
+};