spectrum-ts 1.16.0 → 1.17.0

package/dist/{attachment-Bz66JIjW.d.ts → attachment-DfWSZS5L.d.ts}

@@ -1,5 +1,5 @@
 import z__default from 'zod';
-import { C as ContentBuilder } from './types-Dqv4Ffqg.js';
+import { C as ContentBuilder } from './types-DcQ5a7PK.js';
 
 declare const attachmentSchema: z__default.ZodObject<{
     type: z__default.ZodLiteral<"attachment">;

package/dist/{authoring-e7xyaumK.d.ts → authoring-C9uDdZ2F.d.ts}

@@ -1,7 +1,7 @@
-import './attachment-Bz66JIjW.js';
+import './attachment-DfWSZS5L.js';
 import vCard from 'vcf';
 import z__default from 'zod';
-import { U as User, C as ContentBuilder, M as Message, b as Space, c as ContentInput } from './types-Dqv4Ffqg.js';
+import { U as User, C as ContentBuilder, M as Message, b as Space, c as ContentInput } from './types-DcQ5a7PK.js';
 
 declare const nameSchema: z__default.ZodObject<{
     formatted: z__default.ZodOptional<z__default.ZodString>;

package/dist/authoring.d.ts

@@ -1,6 +1,6 @@
-export { c as asAttachment } from './attachment-Bz66JIjW.js';
-export { s as asContact, u as asCustom, w as asGroup, x as asPoll, y as asPollOption, z as asReaction, A as asRichlink, B as asText, D as asVoice } from './authoring-e7xyaumK.js';
-export { f as ProviderMessageRecord } from './types-Dqv4Ffqg.js';
+export { c as asAttachment } from './attachment-DfWSZS5L.js';
+export { s as asContact, u as asCustom, w as asGroup, x as asPoll, y as asPollOption, z as asReaction, A as asRichlink, B as asText, D as asVoice } from './authoring-C9uDdZ2F.js';
+export { f as ProviderMessageRecord } from './types-DcQ5a7PK.js';
 import 'zod';
 import 'vcf';
 import 'hotscript';

package/dist/{chunk-PIULC4CM.js → chunk-DK4P2SHC.js}

@@ -11,7 +11,7 @@ import {
   cloud,
   mergeStreams,
   stream
-} from "./chunk-VNMOZFWV.js";
+} from "./chunk-KYEHKHXT.js";
 import {
   asContact,
   fromVCard,
@@ -1650,6 +1650,53 @@ var resumableOrderedStream = (options) => stream((emit, end) => {
   };
 });
 
+// src/providers/imessage/remote/contact-share.ts
+import { sanitizeErrorMessage } from "@photon-ai/otel";
+import { LRUCache } from "lru-cache";
+var SHARE_TTL_MS = 24 * 60 * 60 * 1e3;
+var MAX_TRACKED_CHATS = 1e4;
+var ContactShareTracker = class {
+  cache = new LRUCache({
+    max: MAX_TRACKED_CHATS,
+    ttl: SHARE_TTL_MS,
+    ttlAutopurge: false
+  });
+  /**
+   * Best-effort share. The cache is set eagerly so that a burst of inbound
+   * messages for the same chat coalesces to a single API call. On failure the
+   * entry is evicted so the next inbound retries — transient errors don't
+   * permanently mute the feature for a chat. Never awaits and never throws:
+   * the receive stream must not crash on share failures.
+   */
+  maybeShare(client, chatGuid) {
+    if (this.cache.has(chatGuid)) {
+      return;
+    }
+    this.cache.set(chatGuid, true);
+    const safeChatGuid = sanitizeErrorMessage(chatGuid);
+    client.chats.shareContactInfo(chatGuid).then(() => {
+      console.info(
+        `[spectrum-ts][imessage][contact-share] shared contact info to ${safeChatGuid}`
+      );
+    }).catch((error) => {
+      this.cache.delete(chatGuid);
+      console.warn(
+        `[spectrum-ts][imessage][contact-share] failed to share contact info to ${safeChatGuid}`,
+        error
+      );
+    });
+  }
+};
+var trackers = /* @__PURE__ */ new WeakMap();
+var getContactShareTracker = (owner) => {
+  let tracker = trackers.get(owner);
+  if (!tracker) {
+    tracker = new ContactShareTracker();
+    trackers.set(owner, tracker);
+  }
+  return tracker;
+};
+
 // src/providers/imessage/remote/polls.ts
 var isVotedPollEvent = (event) => event.delta.type === "voted";
 var isUnvotedPollEvent = (event) => event.delta.type === "unvoted";
@@ -1789,11 +1836,15 @@ var isRetryableIMessageStreamError = (error) => {
   return false;
 };
 var isEventFromCurrentAccount = (event, phone) => event.isFromMe || phone !== SHARED_PHONE && event.actor?.address !== void 0 && event.actor.address === phone;
-var toMessageItem = async (client, event, phone, cursor) => {
+var toMessageItem = async (client, event, phone, cursor, onInbound) => {
   if (event.type === "message.received") {
     if (event.message.isFromMe) {
       return { cursor, id: event.message.guid, values: [] };
     }
+    const inboundChatGuid = event.message.chatGuids?.[0];
+    if (inboundChatGuid) {
+      onInbound?.(inboundChatGuid);
+    }
     const cache = getMessageCache(client);
     return {
       cursor,
@@ -1884,11 +1935,17 @@ var withClose = (source, cursor) => Object.assign(afterCursor(source, cursor), {
     await source.close?.();
   }
 });
-var messageStream = (client, phone) => resumableOrderedStream({
+var messageStream = (client, phone, onInbound) => resumableOrderedStream({
   fetchMissed: (cursor) => catchUpEvents(client, cursor, isMessageEvent),
   isRetryableError: isRetryableIMessageStreamError,
-  processLive: (event) => toMessageItem(client, event, phone, String(event.sequence)),
-  processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toMessageItem(client, event, phone, String(event.sequence)),
+  processLive: (event) => toMessageItem(client, event, phone, String(event.sequence), onInbound),
+  processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toMessageItem(
+    client,
+    event,
+    phone,
+    String(event.sequence),
+    onInbound
+  ),
   subscribeLive: (cursor) => withClose(client.messages.subscribeEvents(), cursor)
 });
 var pollStream = (client, pollCache, phone) => resumableOrderedStream({
@@ -1898,14 +1955,23 @@ var pollStream = (client, pollCache, phone) => resumableOrderedStream({
   processMissed: (event) => event.type === "catchup.complete" ? Promise.resolve(toCatchUpCompleteItem(event)) : toPollItem(client, pollCache, event, phone, String(event.sequence)),
   subscribeLive: (cursor) => withClose(client.polls.subscribeEvents(), cursor)
 });
-var clientStream = (client, pollCache, phone) => mergeStreams([
-  messageStream(client, phone),
+var clientStream = (client, pollCache, phone, onInbound) => mergeStreams([
+  messageStream(client, phone, onInbound),
   pollStream(client, pollCache, phone)
 ]);
-var messages3 = (clients) => {
+var messages3 = (clients, projectConfig) => {
   const pollCache = getPollCache(clients);
+  const shareEnabled = projectConfig?.profile?.imessageSynced === true;
+  const tracker = shareEnabled ? getContactShareTracker(clients) : void 0;
   return mergeStreams(
-    clients.map((entry) => clientStream(entry.client, pollCache, entry.phone))
+    clients.map(
+      (entry) => clientStream(
+        entry.client,
+        pollCache,
+        entry.phone,
+        tracker ? (chatGuid) => tracker.maybeShare(entry.client, chatGuid) : void 0
+      )
+    )
   );
 };
 
@@ -1918,7 +1984,7 @@ var stopTyping = async (remote, spaceId) => {
 };
 
 // src/providers/imessage/remote/api.ts
-var messages4 = (clients) => messages3(clients);
+var messages4 = (clients, projectConfig) => messages3(clients, projectConfig);
 var setBackground2 = async (remote, spaceId, content) => setBackground(remote, spaceId, content);
 var setDisplayName2 = async (remote, spaceId, content) => setDisplayName(remote, spaceId, content);
 var setIcon2 = async (remote, spaceId, content) => setIcon(remote, spaceId, content);
@@ -2159,7 +2225,7 @@ var imessage = definePlatform("iMessage", {
       }
     }
   },
-  messages: ({ client }) => isLocal(client) ? messages2(client) : messages4(client),
+  messages: ({ client, projectConfig }) => isLocal(client) ? messages2(client) : messages4(client, projectConfig),
   send: async ({ space, content, client }) => {
     if (content.type === "reply") {
       if (isLocal(client)) {

package/dist/{chunk-753K5YPL.js → chunk-GHERTIUM.js}

@@ -5,7 +5,7 @@ import {
   cloud,
   mergeStreams,
   stream
-} from "./chunk-VNMOZFWV.js";
+} from "./chunk-KYEHKHXT.js";
 import {
   asContact
 } from "./chunk-RNGEA4UW.js";

package/dist/{chunk-VNMOZFWV.js → chunk-KYEHKHXT.js}

@@ -44,6 +44,9 @@ var request = async (path, init) => {
 };
 var basicAuth = (projectId, projectSecret) => `Basic ${btoa(`${projectId}:${projectSecret}`)}`;
 var cloud = {
+  getProject: (projectId, projectSecret) => request(`/projects/${projectId}/`, {
+    headers: { Authorization: basicAuth(projectId, projectSecret) }
+  }),
   getSubscription: (projectId) => request(`/projects/${projectId}/billing/subscription`),
   issueImessageTokens: (projectId, projectSecret) => request(`/projects/${projectId}/imessage/tokens`, {
     method: "POST",

package/dist/{chunk-UFAZMTKC.js → chunk-Y4CZ5JFD.js}

@@ -2,7 +2,7 @@ import {
   cloud,
   mergeStreams,
   stream
-} from "./chunk-VNMOZFWV.js";
+} from "./chunk-KYEHKHXT.js";
 import {
   UnsupportedError,
   definePlatform

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-export { A as Attachment, a as AttachmentInput, b as attachment } from './attachment-Bz66JIjW.js';
+export { A as Attachment, a as AttachmentInput, b as attachment } from './attachment-DfWSZS5L.js';
 import z__default from 'zod';
 import { P as PhotoInput } from './photo-content-BJKnqgN-.js';
-import { C as ContentBuilder, M as Message, U as User, b as Space, c as ContentInput, e as Content, f as ProviderMessageRecord, g as SpaceActionFn, h as MessageActionFn, i as CreateClientContext, d as Store, P as Platform, a as PlatformDef, j as ProviderMessage, E as EventProducer, I as InstanceActionFn, k as PlatformProviderConfig, l as SpectrumLike, m as CustomEventStreams, A as AgentSender } from './types-Dqv4Ffqg.js';
-export { n as AnyPlatformDef, B as Broadcaster, o as ManagedStream, p as PlatformInstance, q as PlatformMessage, r as PlatformRuntime, s as PlatformSpace, t as PlatformUser, S as SchemaMessage, u as broadcast, v as mergeStreams, w as stream } from './types-Dqv4Ffqg.js';
-import { C as ContactInput, a as Contact } from './authoring-e7xyaumK.js';
-export { b as ContactAddress, c as ContactDetails, d as ContactEmail, e as ContactName, f as ContactOrg, g as ContactPhone, G as Group, P as Poll, h as PollChoice, i as PollChoiceInput, j as PollOption, R as Reaction, k as Richlink, V as Voice, l as contact, m as custom, n as group, o as option, p as poll, r as reaction, q as richlink, t as text, v as voice } from './authoring-e7xyaumK.js';
+import { C as ContentBuilder, M as Message, U as User, b as Space, c as ContentInput, e as Content, f as ProviderMessageRecord, g as SpaceActionFn, h as MessageActionFn, i as CreateClientContext, d as Store, P as Platform, a as PlatformDef, j as ProviderMessage, E as EventProducer, I as InstanceActionFn, k as PlatformProviderConfig, l as SpectrumLike, m as CustomEventStreams, A as AgentSender, n as ProjectData } from './types-DcQ5a7PK.js';
+export { o as AnyPlatformDef, B as Broadcaster, p as CloudPlatform, D as DedicatedTokenData, F as FusorTokenData, q as ImessageInfoData, r as ManagedStream, s as PlatformInstance, t as PlatformMessage, u as PlatformRuntime, v as PlatformSpace, w as PlatformStatus, x as PlatformUser, y as PlatformsData, z as ProjectProfile, S as SchemaMessage, G as SharedTokenData, H as SlackTeamMeta, J as SlackTokenData, K as SpectrumCloudError, L as SubscriptionData, N as SubscriptionStatus, T as TokenData, O as broadcast, Q as cloud, R as mergeStreams, V as stream } from './types-DcQ5a7PK.js';
+import { C as ContactInput, a as Contact } from './authoring-C9uDdZ2F.js';
+export { b as ContactAddress, c as ContactDetails, d as ContactEmail, e as ContactName, f as ContactOrg, g as ContactPhone, G as Group, P as Poll, h as PollChoice, i as PollChoiceInput, j as PollOption, R as Reaction, k as Richlink, V as Voice, l as contact, m as custom, n as group, o as option, p as poll, r as reaction, q as richlink, t as text, v as voice } from './authoring-C9uDdZ2F.js';
 import 'hotscript';
 import 'vcf';
 
@@ -2629,8 +2629,17 @@ interface FusorClient<TPayload = unknown> {
 /**
  * Request-scoped handler invoked once per inbound message that
  * `spectrum.webhook()` resolves. Receives the same fully-built `[space,
- * message]` pair that `spectrum.messages` yields; awaited before the HTTP
- * response is returned to fusor.
+ * message]` pair that `spectrum.messages` yields.
+ *
+ * Runs **fire-and-forget**: it is dispatched after the HTTP response (the
+ * platform's `respond()` reply) has already been computed, so its outcome never
+ * affects the response, and a throw is caught + logged rather than surfaced —
+ * mirroring the body of a `for await (… of spectrum.messages)` loop.
+ *
+ * On a long-running server the event loop keeps the handler alive. On
+ * serverless/edge runtimes the function may be frozen once the response is
+ * returned, so keeping background work alive is the caller's responsibility —
+ * the usual pattern is to enqueue the work and process it in a separate worker.
  */
 type WebhookHandler = (space: Space, message: Message) => void | Promise<void>;
 /**
@@ -2752,9 +2761,17 @@ type SpectrumInstance<Providers extends PlatformProviderConfig[] = PlatformProvi
     /**
      * Handle one inbound fusor webhook delivery. Call this from your HTTP
      * server's POST route — it verifies, decodes, routes to the matching
-     * provider's verify + message pipeline, invokes `handler` once per resolved
-     * message, and returns the HTTP response fusor relays back to the platform
-     * (including protocol echoes like Slack `url_verification`).
+     * provider's verify + message pipeline, and returns the HTTP response fusor
+     * relays back to the platform: the platform's `respond()` reply (including
+     * protocol echoes like Slack `url_verification`), computed synchronously and
+     * returned immediately.
+     *
+     * `handler` is invoked once per resolved message **fire-and-forget** — it is
+     * dispatched after the response is computed and is NOT awaited, so its
+     * outcome never changes the response (a throw is logged, not surfaced). On a
+     * long-running server the event loop keeps it alive; on serverless/edge,
+     * keeping the work alive past the response is the caller's job (e.g. enqueue
+     * and process in a separate worker).
      *
      * Stateless and request-scoped: it does NOT feed `spectrum.messages`, and it
      * never opens the gRPC stream. fusor delivers at-least-once, so `handler`
@@ -2786,7 +2803,10 @@ declare function Spectrum<const Providers extends PlatformProviderConfig[]>(opti
     options?: SpectrumOptions;
     telemetry?: boolean;
     webhookSecret?: string;
-} | {
+}): Promise<SpectrumInstance<Providers> & {
+    readonly config: ProjectData;
+}>;
+declare function Spectrum<const Providers extends PlatformProviderConfig[]>(options: {
     projectId?: never;
     projectSecret?: never;
     providers: [...Providers];
@@ -2795,67 +2815,6 @@ declare function Spectrum<const Providers extends PlatformProviderConfig[]>(opti
     webhookSecret?: string;
 }): Promise<SpectrumInstance<Providers>>;
 
-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;
-    numbers: Record<string, string | null>;
-    type: "dedicated";
-}
-type TokenData = SharedTokenData | DedicatedTokenData;
-type CloudPlatform = "imessage" | "whatsapp_business" | "slack";
-interface PlatformStatus {
-    enabled: boolean;
-}
-type PlatformsData = Record<CloudPlatform, PlatformStatus>;
-interface ImessageInfoData {
-    type: "shared" | "dedicated";
-}
-interface WhatsappBusinessTokenData {
-    auth: Record<string, string>;
-    expiresIn: number;
-    numbers: Record<string, string | null>;
-}
-interface SlackTeamMeta {
-    appId: string;
-    botUserId: string;
-    grantedScopes: string[];
-    teamName: string;
-}
-interface SlackTokenData {
-    auth: Record<string, string>;
-    expiresIn: number;
-    teams: Record<string, SlackTeamMeta>;
-}
-interface FusorTokenData {
-    expiresIn: number;
-    token: string;
-}
-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>;
-    issueWhatsappBusinessTokens: (projectId: string, projectSecret: string) => Promise<WhatsappBusinessTokenData>;
-    issueSlackTokens: (projectId: string, projectSecret: string) => Promise<SlackTokenData>;
-    issueFusorToken: (projectId: string, projectSecret: string) => Promise<FusorTokenData>;
-    getPlatforms: (projectId: string) => Promise<PlatformsData>;
-    togglePlatform: (projectId: string, projectSecret: string, platform: CloudPlatform, enabled: boolean) => Promise<PlatformsData>;
-};
-
 type UnsupportedKind = "content" | "action";
 interface UnsupportedErrorOptions {
     action?: string;
@@ -2879,4 +2838,4 @@ declare class UnsupportedError extends Error {
 declare const fromVCard: (vcf: string) => ContactInput;
 declare const toVCard: (contact: Contact) => Promise<string>;
 
-export { AgentSender, type Avatar, type AvatarInput, type CloudPlatform, Contact, ContactInput, Content, ContentBuilder, ContentInput, type DedicatedTokenData, type Edit, Emoji, type EmojiKey, EventProducer, type FusorClient, type FusorMessages, type FusorMessagesCtx, type FusorMessagesReturn, type FusorReply, type FusorRespond, type FusorTokenData, type FusorVerify, type FusorVerifyRequest, type ImessageInfoData, Message, Platform, PlatformDef, PlatformProviderConfig, type PlatformStatus, type PlatformsData, ProviderMessage, type Rename, type Reply, type SharedTokenData, type SlackTeamMeta, type SlackTokenData, Space, Spectrum, SpectrumCloudError, type SpectrumInstance, type SubscriptionData, type SubscriptionStatus, type TokenData, type Typing, UnsupportedError, type UnsupportedKind, User, type WebhookHandler, type WebhookRawRequest, type WebhookRawResult, avatar, cloud, defineFusorPlatform, definePlatform, edit, fromVCard, fusor, isFusorClient, rename, reply, resolveContents, toVCard, typing };
+export { AgentSender, type Avatar, type AvatarInput, Contact, ContactInput, Content, ContentBuilder, ContentInput, type Edit, Emoji, type EmojiKey, EventProducer, type FusorClient, type FusorMessages, type FusorMessagesCtx, type FusorMessagesReturn, type FusorReply, type FusorRespond, type FusorVerify, type FusorVerifyRequest, Message, Platform, PlatformDef, PlatformProviderConfig, ProjectData, ProviderMessage, type Rename, type Reply, Space, Spectrum, type SpectrumInstance, type Typing, UnsupportedError, type UnsupportedKind, User, type WebhookHandler, type WebhookRawRequest, type WebhookRawResult, avatar, defineFusorPlatform, definePlatform, edit, fromVCard, fusor, isFusorClient, rename, reply, resolveContents, toVCard, typing };

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   createAsyncQueue,
   mergeStreams,
   stream
-} from "./chunk-VNMOZFWV.js";
+} from "./chunk-KYEHKHXT.js";
 import {
   contact,
   fromVCard,
@@ -27639,6 +27639,7 @@ async function Spectrum(options) {
   } = options;
   const flattenGroups = runtimeOptions?.flattenGroups ?? false;
   const otelHandle = telemetry ? bootstrapTelemetry({ projectId, projectSecret }) : void 0;
+  const projectConfig = projectId !== void 0 && projectSecret !== void 0 ? await cloud.getProject(projectId, projectSecret) : void 0;
   const platformStates = /* @__PURE__ */ new Map();
   const fusorMessageSources = /* @__PURE__ */ new Map();
   const messageBroadcasters = /* @__PURE__ */ new Map();
@@ -27719,6 +27720,7 @@ async function Spectrum(options) {
     const raw = fusorSource ? fusorSource.iterable : definition.messages({
       client,
       config,
+      projectConfig,
       store
     });
     const bindSend = async function* () {
@@ -27859,7 +27861,12 @@ async function Spectrum(options) {
       if (!producer) {
         continue;
       }
-      const providerEvents = producer({ client, config, store });
+      const providerEvents = producer({
+        client,
+        config,
+        projectConfig,
+        store
+      });
       const annotatePlatform = async function* () {
         for await (const value of providerEvents) {
           const annotated = await withSpan(
@@ -28013,11 +28020,23 @@ async function Spectrum(options) {
     }
     return { asWeb: false, bodyBytes, headers };
   };
-  const deliverWebhookMessages = async (collected, runtime, handler) => {
+  const deliverWebhookMessages = async (collected, runtime, handler, event) => {
     for (const record of collected) {
       const tuples = await resolveRecordToMessages(record, runtime);
       for (const [space, message] of tuples) {
-        await handler(space, message);
+        try {
+          await handler(space, message);
+        } catch (error) {
+          lifecycleLog.error(
+            `spectrum.webhook: handler threw (async), ${error}`,
+            {
+              eventId: event.eventId,
+              platform: event.platform,
+              messageId: message.id,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        }
       }
     }
   };
@@ -28037,19 +28056,6 @@ async function Spectrum(options) {
       return null;
     }
   };
-  const runWebhookDelivery = async (collected, runtime, handler, event) => {
-    try {
-      await deliverWebhookMessages(collected, runtime, handler);
-      return null;
-    } catch (error) {
-      lifecycleLog.error(`spectrum.webhook: handler threw, ${error}`, {
-        eventId: event.eventId,
-        platform: event.platform,
-        error: error instanceof Error ? error.message : String(error)
-      });
-      return { status: 500, headers: {}, body: new Uint8Array(0) };
-    }
-  };
   const processWebhookEvent = async (core, event, handler) => {
     const collected = [];
     const reply2 = await core.processEvent(event, (record) => {
@@ -28062,23 +28068,27 @@ async function Spectrum(options) {
         body: encodeText(reply2.errorReason)
       };
     }
-    const runtime = platformStates.get(event.platform);
-    if (runtime) {
-      const failure = await runWebhookDelivery(
-        collected,
-        runtime,
-        handler,
-        event
-      );
-      if (failure) {
-        return failure;
-      }
-    }
-    return {
+    const result = {
       status: reply2.status === 0 ? 200 : reply2.status,
       headers: reply2.headers ?? {},
       body: reply2.body ?? new Uint8Array(0)
     };
+    const runtime = platformStates.get(event.platform);
+    if (runtime && collected.length > 0) {
+      deliverWebhookMessages(collected, runtime, handler, event).catch(
+        (error) => {
+          lifecycleLog.error(
+            `spectrum.webhook: delivery failed (async), ${error}`,
+            {
+              eventId: event.eventId,
+              platform: event.platform,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        }
+      );
+    }
+    return result;
   };
   const handleWebhook = async (request, handler) => {
     if (!fusorCore) {
@@ -28113,6 +28123,7 @@ async function Spectrum(options) {
   const base = {
     __providers: providers,
     __internal: { platforms: platformStates },
+    config: projectConfig,
     messages,
     stop: stopOnce,
     webhook: handleWebhook,

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

@@ -1,8 +1,8 @@
-import { C as ContentBuilder, c as ContentInput, M as Message, S as SchemaMessage, P as Platform, a as PlatformDef, b as Space, d as Store } from '../../types-Dqv4Ffqg.js';
+import { C as ContentBuilder, c as ContentInput, M as Message, S as SchemaMessage, P as Platform, a as PlatformDef, b as Space, d as Store } from '../../types-DcQ5a7PK.js';
 import * as zod_v4_core from 'zod/v4/core';
 import * as z from 'zod';
 import z__default from 'zod';
-import { A as Attachment } from '../../attachment-Bz66JIjW.js';
+import { A as Attachment } from '../../attachment-DfWSZS5L.js';
 import { P as PhotoInput } from '../../photo-content-BJKnqgN-.js';
 import { MessageEffect, AdvancedIMessage } from '@photon-ai/advanced-imessage';
 import { IMessageSDK } from '@photon-ai/imessage-kit';

package/dist/providers/imessage/index.js

@@ -3,10 +3,10 @@ import {
   effect,
   imessage,
   read
-} from "../../chunk-PIULC4CM.js";
+} from "../../chunk-DK4P2SHC.js";
 import "../../chunk-LJM5D2T5.js";
 import "../../chunk-KO67KDBD.js";
-import "../../chunk-VNMOZFWV.js";
+import "../../chunk-KYEHKHXT.js";
 import "../../chunk-RNGEA4UW.js";
 import "../../chunk-32H3VVUE.js";
 import "../../chunk-FTLJVVH7.js";

package/dist/providers/index.d.ts

@@ -2,11 +2,11 @@ export { imessage } from './imessage/index.js';
 export { slack } from './slack/index.js';
 export { terminal } from './terminal/index.js';
 export { whatsappBusiness } from './whatsapp-business/index.js';
-import '../types-Dqv4Ffqg.js';
+import '../types-DcQ5a7PK.js';
 import 'hotscript';
 import 'zod';
 import 'zod/v4/core';
-import '../attachment-Bz66JIjW.js';
+import '../attachment-DfWSZS5L.js';
 import '../photo-content-BJKnqgN-.js';
 import '@photon-ai/advanced-imessage';
 import '@photon-ai/imessage-kit';

package/dist/providers/index.js

@@ -1,19 +1,19 @@
 import {
   imessage
-} from "../chunk-PIULC4CM.js";
+} from "../chunk-DK4P2SHC.js";
 import "../chunk-LJM5D2T5.js";
 import {
   slack
-} from "../chunk-UFAZMTKC.js";
+} from "../chunk-Y4CZ5JFD.js";
 import {
   terminal
 } from "../chunk-6NGVREPQ.js";
 import "../chunk-5QSNQ6YN.js";
 import {
   whatsappBusiness
-} from "../chunk-753K5YPL.js";
+} from "../chunk-GHERTIUM.js";
 import "../chunk-KO67KDBD.js";
-import "../chunk-VNMOZFWV.js";
+import "../chunk-KYEHKHXT.js";
 import "../chunk-RNGEA4UW.js";
 import "../chunk-32H3VVUE.js";
 import "../chunk-FTLJVVH7.js";

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

@@ -1,4 +1,4 @@
-import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-Dqv4Ffqg.js';
+import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-DcQ5a7PK.js';
 import * as z from 'zod';
 import z__default from 'zod';
 import * as _photon_ai_slack from '@photon-ai/slack';

package/dist/providers/slack/index.js

@@ -1,7 +1,7 @@
 import {
   slack
-} from "../../chunk-UFAZMTKC.js";
-import "../../chunk-VNMOZFWV.js";
+} from "../../chunk-Y4CZ5JFD.js";
+import "../../chunk-KYEHKHXT.js";
 import "../../chunk-32H3VVUE.js";
 import "../../chunk-FTLJVVH7.js";
 export {

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

@@ -1,4 +1,4 @@
-import { P as Platform, a as PlatformDef, M as Message, U as User, b as Space } from '../../types-Dqv4Ffqg.js';
+import { P as Platform, a as PlatformDef, M as Message, U as User, b as Space } from '../../types-DcQ5a7PK.js';
 import { ChildProcess } from 'node:child_process';
 import z__default from 'zod';
 import { Socket } from 'node:net';

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

@@ -1,4 +1,4 @@
-import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-Dqv4Ffqg.js';
+import { S as SchemaMessage, P as Platform, a as PlatformDef } from '../../types-DcQ5a7PK.js';
 import { WhatsAppClient } from '@photon-ai/whatsapp-business';
 import * as z from 'zod';
 import z__default from 'zod';

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

@@ -1,8 +1,8 @@
 import {
   whatsappBusiness
-} from "../../chunk-753K5YPL.js";
+} from "../../chunk-GHERTIUM.js";
 import "../../chunk-KO67KDBD.js";
-import "../../chunk-VNMOZFWV.js";
+import "../../chunk-KYEHKHXT.js";
 import "../../chunk-RNGEA4UW.js";
 import "../../chunk-32H3VVUE.js";
 import "../../chunk-FTLJVVH7.js";

package/dist/{types-Dqv4Ffqg.d.ts → types-DcQ5a7PK.d.ts}

@@ -762,6 +762,85 @@ interface Message<TPlatform extends string = string, TSender extends User = User
     timestamp: Date;
 }
 
+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;
+    numbers: Record<string, string | null>;
+    type: "dedicated";
+}
+type TokenData = SharedTokenData | DedicatedTokenData;
+type CloudPlatform = "imessage" | "whatsapp_business" | "slack";
+interface PlatformStatus {
+    enabled: boolean;
+}
+type PlatformsData = Record<CloudPlatform, PlatformStatus>;
+interface ImessageInfoData {
+    type: "shared" | "dedicated";
+}
+interface WhatsappBusinessTokenData {
+    auth: Record<string, string>;
+    expiresIn: number;
+    numbers: Record<string, string | null>;
+}
+interface SlackTeamMeta {
+    appId: string;
+    botUserId: string;
+    grantedScopes: string[];
+    teamName: string;
+}
+interface SlackTokenData {
+    auth: Record<string, string>;
+    expiresIn: number;
+    teams: Record<string, SlackTeamMeta>;
+}
+interface FusorTokenData {
+    expiresIn: number;
+    token: string;
+}
+/**
+ * Per-project profile bag — a flexible record of project-level settings
+ * defined in Spectrum Cloud. Concrete fields depend on the project; consumers
+ * read them as `app.config.profile.<key>`.
+ */
+interface ProjectProfile {
+    [key: string]: unknown;
+}
+/**
+ * The project record returned by `GET /projects/{projectId}/`. Populated on
+ * `app.config` when `Spectrum()` is called with `projectId` + `projectSecret`.
+ */
+interface ProjectData {
+    id: string;
+    name: string;
+    profile: ProjectProfile;
+}
+declare class SpectrumCloudError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+declare const cloud: {
+    getProject: (projectId: string, projectSecret: string) => Promise<ProjectData>;
+    getSubscription: (projectId: string) => Promise<SubscriptionData>;
+    issueImessageTokens: (projectId: string, projectSecret: string) => Promise<TokenData>;
+    getImessageInfo: (projectId: string) => Promise<ImessageInfoData>;
+    issueWhatsappBusinessTokens: (projectId: string, projectSecret: string) => Promise<WhatsappBusinessTokenData>;
+    issueSlackTokens: (projectId: string, projectSecret: string) => Promise<SlackTokenData>;
+    issueFusorToken: (projectId: string, projectSecret: string) => Promise<FusorTokenData>;
+    getPlatforms: (projectId: string) => Promise<PlatformsData>;
+    togglePlatform: (projectId: string, projectSecret: string, platform: CloudPlatform, enabled: boolean) => Promise<PlatformsData>;
+};
+
 /**
  * A small per-platform key-value bag, modeled after Swift's `UserDefaults`.
  * Untyped writes; typed reads return `undefined` on missing key OR type
@@ -891,6 +970,13 @@ type InputSchema<TSchema> = TSchema extends z__default.ZodType<object> ? z__defa
 type EventProducer<TPayload = unknown, TClient = unknown, TConfig = unknown> = (ctx: {
     client: NoInferClient<TClient>;
     config: TConfig;
+    /**
+     * Spectrum Cloud project metadata, fetched once at `Spectrum()` init.
+     * `undefined` when the instance was created without `projectId`/`projectSecret`
+     * (local-only setups). Providers read project-level toggles from
+     * `projectConfig.profile.<key>` — e.g. iMessage's `imessageSynced` flag.
+     */
+    projectConfig: ProjectData | undefined;
     store: Store;
 }) => AsyncIterable<TPayload>;
 type ProviderMessage<TSender extends ResolvedUser = ResolvedUser, TSpace extends ResolvedSpace = ResolvedSpace, TExtra extends object = Record<never, never>> = {
@@ -925,7 +1011,7 @@ type ProviderMessageRecord = {
 type MergeSchema<TSchema extends z__default.ZodType | undefined, TBase extends object> = TSchema extends z__default.ZodType ? string extends keyof z__default.infer<TSchema> ? TBase : Omit<z__default.infer<TSchema>, keyof TBase> & TBase : TBase;
 type SchemaMessage<TUserSchema extends z__default.ZodType | undefined = undefined, TSpaceSchema extends z__default.ZodType | undefined = undefined> = ProviderMessage<MergeSchema<TUserSchema, ResolvedUser>, MergeSchema<TSpaceSchema, ResolvedSpace>>;
 type InferEventPayload<T> = T extends (ctx: never) => AsyncIterable<infer P> ? P : never;
-type ReservedNames = "stop" | "send" | "__internal" | "__providers";
+type ReservedNames = "stop" | "send" | "config" | "__internal" | "__providers";
 interface CreateClientContext<_ConfigSchema extends z__default.ZodType<object>> {
     config: z__default.infer<_ConfigSchema>;
     projectId: string | undefined;
@@ -1237,4 +1323,4 @@ interface Platform<Def extends AnyPlatformDef> {
     (message: Message): PlatformMessage<Def>;
 }
 
-export { type AgentSender as A, type Broadcaster as B, type ContentBuilder as C, type EventProducer as E, type InstanceActionFn as I, type Message as M, type Platform as P, type SchemaMessage as S, type User as U, type PlatformDef as a, type Space as b, type ContentInput as c, type Store as d, type Content as e, type ProviderMessageRecord as f, type SpaceActionFn as g, type MessageActionFn as h, type CreateClientContext as i, type ProviderMessage as j, type PlatformProviderConfig as k, type SpectrumLike as l, type CustomEventStreams as m, type AnyPlatformDef as n, type ManagedStream as o, type PlatformInstance as p, type PlatformMessage as q, type PlatformRuntime as r, type PlatformSpace as s, type PlatformUser as t, broadcast as u, mergeStreams as v, stream as w };
+export { type AgentSender as A, type Broadcaster as B, type ContentBuilder as C, type DedicatedTokenData as D, type EventProducer as E, type FusorTokenData as F, type SharedTokenData as G, type SlackTeamMeta as H, type InstanceActionFn as I, type SlackTokenData as J, SpectrumCloudError as K, type SubscriptionData as L, type Message as M, type SubscriptionStatus as N, broadcast as O, type Platform as P, cloud as Q, mergeStreams as R, type SchemaMessage as S, type TokenData as T, type User as U, stream as V, type PlatformDef as a, type Space as b, type ContentInput as c, type Store as d, type Content as e, type ProviderMessageRecord as f, type SpaceActionFn as g, type MessageActionFn as h, type CreateClientContext as i, type ProviderMessage as j, type PlatformProviderConfig as k, type SpectrumLike as l, type CustomEventStreams as m, type ProjectData as n, type AnyPlatformDef as o, type CloudPlatform as p, type ImessageInfoData as q, type ManagedStream as r, type PlatformInstance as s, type PlatformMessage as t, type PlatformRuntime as u, type PlatformSpace as v, type PlatformStatus as w, type PlatformUser as x, type PlatformsData as y, type ProjectProfile as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spectrum-ts",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Bring agents to any interface — unified messaging SDK for TypeScript.",
   "repository": {
     "type": "git",
@@ -45,6 +45,8 @@
     "@photon-ai/whatsapp-business": "^0.1.1",
     "@photon-ai/proto": "^0.2.4",
     "@repeaterjs/repeater": "^3.0.6",
+    "better-grpc": "^0.3.2",
+    "lru-cache": "^11.0.0",
     "mime-types": "^3.0.1",
     "nice-grpc": "^2.1.16",
     "nice-grpc-common": "^2.0.2",