spectrum-ts 0.2.2 → 0.4.0

package/src/spectrum.ts

@@ -1,390 +0,0 @@
-import z from "zod";
-import type {
-  AnyPlatformDef,
-  CustomEventStreams,
-  PlatformProviderConfig,
-  SpectrumLike,
-} from "./platform/types";
-import type { Content, ContentBuilder } from "./types/content";
-import type { Message } from "./types/message";
-import type { Space } from "./types/space";
-import { type ManagedStream, mergeStreams, stream } from "./utils/stream";
-
-type ProviderMessageRecord = {
-  id: string;
-  content: Content[];
-  sender: { id: string } & Record<string, unknown>;
-  space: { id: string } & Record<string, unknown>;
-  timestamp?: Date;
-} & Record<string, unknown>;
-
-const providerMessageCoreKeys = new Set([
-  "content",
-  "id",
-  "sender",
-  "space",
-  "timestamp",
-]);
-
-// ---------------------------------------------------------------------------
-// SpectrumInstance — the typed return of Spectrum()
-// ---------------------------------------------------------------------------
-
-export type SpectrumInstance<
-  Providers extends PlatformProviderConfig[] = PlatformProviderConfig[],
-> = SpectrumLike<Providers> &
-  CustomEventStreams<Providers> & {
-    readonly messages: AsyncIterable<[Space, Message]>;
-    stop(): Promise<void>;
-    send(
-      space: Space,
-      ...content: [ContentBuilder, ...ContentBuilder[]]
-    ): Promise<void>;
-    responding<T>(space: Space, fn: () => T | Promise<T>): Promise<T>;
-  };
-
-// ---------------------------------------------------------------------------
-// Config validation
-// ---------------------------------------------------------------------------
-
-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
-// ---------------------------------------------------------------------------
-
-export async function Spectrum<
-  const Providers extends PlatformProviderConfig[],
->(
-  options:
-    | {
-        projectId: string;
-        projectSecret: string;
-        providers: [...Providers];
-      }
-    | {
-        projectId?: never;
-        projectSecret?: never;
-        providers: [...Providers];
-      }
-): Promise<SpectrumInstance<Providers>> {
-  spectrumConfigSchema.parse(options);
-
-  const { projectId, projectSecret, providers } = options;
-
-  const platformStates = new Map<
-    string,
-    { client: unknown; config: unknown; definition: AnyPlatformDef }
-  >();
-
-  // Custom event streams keyed by event name
-  const customEventStreams = new Map<string, ManagedStream<unknown>>();
-
-  let stopped = false;
-
-  // Initialize all provider clients eagerly
-  for (const provider of providers) {
-    const providerConfig = provider as PlatformProviderConfig;
-    const def = providerConfig.__definition;
-    const userConfig = def.config.parse(providerConfig.config);
-
-    const client = await def.lifecycle.createClient({
-      config: userConfig,
-      projectId,
-      projectSecret,
-    });
-
-    platformStates.set(def.name, {
-      client,
-      config: userConfig,
-      definition: def,
-    });
-  }
-
-  const adaptIterable = <T>(iterable: AsyncIterable<T>): ManagedStream<T> => {
-    return stream<T>((emit, end) => {
-      const iterator = iterable[Symbol.asyncIterator]();
-
-      (async () => {
-        try {
-          let result = await iterator.next();
-          while (!result.done) {
-            emit(result.value);
-            result = await iterator.next();
-          }
-          end();
-        } catch (error) {
-          end(error);
-        }
-      })();
-
-      return async () => {
-        await iterator.return?.();
-      };
-    });
-  };
-
-  const createProviderMessagesStream = (state: {
-    client: unknown;
-    config: unknown;
-    definition: AnyPlatformDef;
-  }): ManagedStream<[Space, Message]> => {
-    const { client, config, definition } = state;
-    const raw = definition.events.messages({
-      client,
-      config,
-    }) as AsyncIterable<ProviderMessageRecord>;
-
-    const bindSend = async function* (): AsyncIterable<[Space, Message]> {
-      for await (const msg of raw) {
-        const extraEntries = Object.entries(msg).filter(
-          ([key]) => !providerMessageCoreKeys.has(key)
-        );
-        const extra = Object.fromEntries(extraEntries);
-        const parsedExtra = definition.message?.schema
-          ? definition.message.schema.parse(extra)
-          : {};
-        const spaceRef = {
-          ...msg.space,
-          __platform: definition.name,
-        };
-        const typingCtx = { space: spaceRef, client, config };
-        const space = {
-          ...spaceRef,
-          send: async (...content: [ContentBuilder, ...ContentBuilder[]]) => {
-            const resolved = await Promise.all(content.map((c) => c.build()));
-            await definition.actions.send({
-              ...typingCtx,
-              content: resolved,
-            });
-          },
-          startTyping: async () => {
-            await definition.actions.startTyping?.(typingCtx);
-          },
-          stopTyping: async () => {
-            await definition.actions.stopTyping?.(typingCtx);
-          },
-          responding: async <T>(fn: () => T | Promise<T>): Promise<T> => {
-            await definition.actions.startTyping?.(typingCtx);
-            try {
-              return await fn();
-            } finally {
-              await definition.actions.stopTyping?.(typingCtx).catch(() => {});
-            }
-          },
-        };
-        const normalizedMessage = {
-          ...parsedExtra,
-          id: msg.id,
-          content: msg.content,
-          platform: definition.name,
-          react: async (reaction: string): Promise<void> => {
-            if (!definition.actions.reactToMessage) {
-              return;
-            }
-            await definition.actions.reactToMessage({
-              space: spaceRef,
-              messageId: msg.id,
-              reaction,
-              client,
-              config,
-            });
-          },
-          reply: async (
-            ...content: [ContentBuilder, ...ContentBuilder[]]
-          ): Promise<void> => {
-            if (!definition.actions.replyToMessage) {
-              return;
-            }
-            const resolved = await Promise.all(content.map((c) => c.build()));
-            await definition.actions.replyToMessage({
-              space: spaceRef,
-              messageId: msg.id,
-              content: resolved,
-              client,
-              config,
-            });
-          },
-          sender: {
-            ...msg.sender,
-            __platform: definition.name,
-          },
-          space,
-          timestamp: msg.timestamp ?? new Date(),
-        };
-
-        yield [space, normalizedMessage];
-      }
-    };
-
-    return adaptIterable(bindSend());
-  };
-
-  const createMessagesStream = (): ManagedStream<[Space, Message]> => {
-    return stream<[Space, Message]>(async (emit, end) => {
-      const merged = mergeStreams(
-        Array.from(platformStates.values(), createProviderMessagesStream)
-      );
-
-      (async () => {
-        try {
-          for await (const value of merged) {
-            emit(value);
-          }
-          end();
-        } catch (error) {
-          end(error);
-        }
-      })();
-
-      return async () => {
-        await merged.close();
-      };
-    });
-  };
-
-  const createCustomEventStream = (
-    eventName: string
-  ): ManagedStream<unknown> => {
-    return stream<unknown>(async (emit, end) => {
-      const providerStreams = Array.from(platformStates.values(), (state) => {
-        const { client, config, definition } = state;
-        const producer = definition.events[eventName] as
-          | ((ctx: {
-              client: unknown;
-              config: unknown;
-            }) => AsyncIterable<unknown>)
-          | undefined;
-        if (!producer) {
-          return undefined;
-        }
-
-        const providerEvents = producer({ client, config });
-        const annotatePlatform = async function* (): AsyncIterable<unknown> {
-          for await (const value of providerEvents) {
-            yield { ...(value as object), platform: definition.name };
-          }
-        };
-
-        return adaptIterable(annotatePlatform());
-      }).filter(
-        (value): value is ManagedStream<unknown> => value !== undefined
-      );
-
-      const merged = mergeStreams(providerStreams);
-
-      (async () => {
-        try {
-          for await (const value of merged) {
-            emit(value);
-          }
-          end();
-        } catch (error) {
-          end(error);
-        }
-      })();
-
-      return async () => {
-        await merged.close();
-      };
-    });
-  };
-
-  const messagesStream = createMessagesStream();
-
-  const stopOnce = async () => {
-    if (stopped) {
-      return;
-    }
-    stopped = true;
-
-    const streamShutdowns = [
-      messagesStream.close(),
-      ...Array.from(customEventStreams.values(), (eventStream) =>
-        eventStream.close()
-      ),
-    ];
-
-    process.off("SIGINT", handleSignal);
-    process.off("SIGTERM", handleSignal);
-
-    await Promise.allSettled(streamShutdowns);
-    const clientShutdowns = Array.from(platformStates.values(), (state) =>
-      state.definition.lifecycle.destroyClient({
-        client: state.client,
-      })
-    );
-    await Promise.allSettled(clientShutdowns);
-    customEventStreams.clear();
-    platformStates.clear();
-  };
-
-  const handleSignal = () => {
-    setTimeout(() => process.exit(1), 3000).unref();
-    stopOnce()
-      .then(() => process.exit(0))
-      .catch(() => process.exit(1));
-  };
-  process.on("SIGINT", handleSignal);
-  process.on("SIGTERM", handleSignal);
-
-  const messages = messagesStream as AsyncIterable<[Space, Message]>;
-
-  // Proxy for flat custom event access (app.typing, app.readReceipt, etc.)
-  const customEventProxy = new Proxy(
-    {} as Record<string, AsyncIterable<unknown>>,
-    {
-      get(_target, prop: string) {
-        let eventStream = customEventStreams.get(prop);
-        if (!eventStream) {
-          eventStream = createCustomEventStream(prop);
-          customEventStreams.set(prop, eventStream);
-        }
-        return eventStream;
-      },
-    }
-  );
-
-  const base = {
-    __providers: providers,
-    __internal: { platforms: platformStates },
-    messages,
-    stop: stopOnce,
-    send: async (
-      space: Space,
-      ...content: [ContentBuilder, ...ContentBuilder[]]
-    ) => {
-      await space.send(...content);
-    },
-    responding: async <T>(
-      space: Space,
-      fn: () => T | Promise<T>
-    ): Promise<T> => {
-      return space.responding(fn);
-    },
-  };
-
-  // Merge base instance with custom event proxy
-  return new Proxy(base, {
-    get(target, prop, receiver) {
-      if (prop in target) {
-        return Reflect.get(target, prop, receiver);
-      }
-      if (typeof prop === "string") {
-        return customEventProxy[prop];
-      }
-      return undefined;
-    },
-  }) as SpectrumInstance<Providers>;
-}

package/src/types/content.ts

@@ -1,85 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-import { lookup as lookupMimeType } from "mime-types";
-import type { NonEmptyString } from "type-fest";
-import z from "zod";
-
-const DEFAULT_ATTACHMENT_NAME = "attachment";
-
-const contentSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("plain_text"),
-    text: z.string().nonempty(),
-  }),
-  z.object({
-    type: z.literal("custom"),
-    raw: z.json(),
-  }),
-  z.object({
-    type: z.literal("attachment"),
-    data: z.instanceof(Buffer),
-    mimeType: z.string().nonempty(),
-    name: z.string().nonempty(),
-  }),
-]);
-
-export type Content = z.infer<typeof contentSchema>;
-
-export interface ContentBuilder {
-  build(): Promise<Content>;
-}
-
-export function text(
-  text: string
-): ContentBuilder {
-  return {
-    build: (): Promise<Content> =>
-      Promise.resolve({ type: "plain_text", text }),
-  };
-}
-
-export function custom(
-  raw: z.infer<ReturnType<typeof z.json>>
-): ContentBuilder {
-  return {
-    build: (): Promise<Content> => Promise.resolve({ type: "custom", raw }),
-  };
-}
-
-const resolveAttachmentName = (input: string | Buffer, name?: string): string =>
-  name ||
-  (typeof input === "string" ? basename(input) : DEFAULT_ATTACHMENT_NAME);
-
-const resolveAttachmentMimeType = (name: string, mimeType?: string): string => {
-  if (mimeType) {
-    return mimeType;
-  }
-
-  const resolvedMimeType = lookupMimeType(name);
-  if (!resolvedMimeType) {
-    throw new Error(
-      `Unable to resolve MIME type for attachment "${name}". Pass options.mimeType explicitly.`
-    );
-  }
-
-  return resolvedMimeType;
-};
-
-export function attachment(
-  input: string | Buffer,
-  options?: { mimeType?: string; name?: string }
-): ContentBuilder {
-  return {
-    build: async (): Promise<Content> => {
-      const data = typeof input === "string" ? await readFile(input) : input;
-      const name = resolveAttachmentName(input, options?.name);
-
-      return {
-        data,
-        mimeType: resolveAttachmentMimeType(name, options?.mimeType),
-        name,
-        type: "attachment",
-      };
-    },
-  };
-}

package/src/types/message.ts

@@ -1,18 +0,0 @@
-import type { Content, ContentBuilder } from "./content";
-import type { Space } from "./space";
-import type { User } from "./user";
-
-export interface Message<
-  TPlatform extends string = string,
-  TSender extends User = User,
-  TSpace extends Space = Space,
-> {
-  content: Content[];
-  readonly id: string;
-  platform: TPlatform;
-  react(reaction: string): Promise<void>;
-  reply(...content: [ContentBuilder, ...ContentBuilder[]]): Promise<void>;
-  sender: TSender;
-  space: TSpace;
-  timestamp: Date;
-}

package/src/types/space.ts

@@ -1,10 +0,0 @@
-import type { ContentBuilder } from "./content";
-
-export interface Space<_Def = unknown> {
-  readonly __platform: string;
-  readonly id: string;
-  responding<T>(fn: () => T | Promise<T>): Promise<T>;
-  send(...content: [ContentBuilder, ...ContentBuilder[]]): Promise<void>;
-  startTyping(): Promise<void>;
-  stopTyping(): Promise<void>;
-}

package/src/types/user.ts

@@ -1,4 +0,0 @@
-export interface User {
-  readonly __platform: string;
-  readonly id: string;
-}

package/src/utils/cloud.ts

@@ -1,147 +0,0 @@
-export const SPECTRUM_CLOUD_URL = `https://${process.env.SPECTRUM_CLOUD_URL ?? "spectrum.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 }),
-    }),
-};