@spectrum-ts/core 9.0.0 → 9.3.0

package/dist/{attachment-Bn3rw5jW.d.ts → attachment-BpPKbxT1.d.ts}

@@ -37,6 +37,7 @@ declare const appSchema: z.ZodObject<{
     imageSubtitle: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>>;
+  live: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 type App = z.infer<typeof appSchema>;
 /**
@@ -45,7 +46,18 @@ type App = z.infer<typeof appSchema>;
  * computed at send time (e.g. minting a signed link).
  */
 type AppUrl = string | Promise<string> | (() => string | Promise<string>);
-declare function app(url: AppUrl): ContentBuilder;
+/** Optional rendering behavior for an app card. */
+interface AppOptions {
+  /** Render the installed app extension's live UI when the platform supports it. */
+  live?: boolean;
+}
+/**
+ * Construct an app card from a URL.
+ *
+ * Pass `{ live: true }` to ask supported platforms to render the installed
+ * app extension's live UI. Other platforms retain their normal URL fallback.
+ */
+declare function app(url: AppUrl, options?: AppOptions): ContentBuilder;
 //#endregion
 //#region src/utils/photo-content.d.ts
 /**
@@ -426,6 +438,16 @@ interface Space<_Def = unknown> {
    * no implementation.
    */
   getAvatar(): Promise<AvatarData | undefined>;
+  /**
+   * Read the current chat's display name (group/chat title). Resolves
+   * `undefined` when the chat has none — an unnamed group, or a 1:1 chat on a
+   * platform that stores no title for DMs. Round-trips into `space.rename()`.
+   *
+   * Universal API; unlike `rename` the read is not group-only. Per-platform
+   * constraints (e.g. iMessage: remote only) surface as `UnsupportedError`, as
+   * do platforms with no implementation.
+   */
+  getDisplayName(): Promise<string | undefined>;
   /**
    * List the chat's current participants, excluding the agent's own account
    * where the platform can identify it. Each entry is a `User` tagged with
@@ -570,6 +592,12 @@ interface Message<TPlatform extends string = string, TSender extends User = User
 declare const editSchema: z.ZodObject<{
   type: z.ZodLiteral<"edit">;
   content: z.ZodCustom<{
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -620,18 +648,9 @@ declare const editSchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -652,13 +671,13 @@ declare const editSchema: z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -671,6 +690,9 @@ declare const editSchema: z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -684,9 +706,16 @@ declare const editSchema: z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -694,12 +723,6 @@ declare const editSchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -726,6 +749,12 @@ declare const editSchema: z.ZodObject<{
   } | {
     type: "leaveSpace";
   }, {
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -776,18 +805,9 @@ declare const editSchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -808,13 +828,13 @@ declare const editSchema: z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -827,6 +847,9 @@ declare const editSchema: z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -840,9 +863,16 @@ declare const editSchema: z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -850,12 +880,6 @@ declare const editSchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -1112,6 +1136,12 @@ declare function rename(displayName: string): ContentBuilder;
 declare const replySchema: z.ZodObject<{
   type: z.ZodLiteral<"reply">;
   content: z.ZodCustom<{
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -1162,18 +1192,9 @@ declare const replySchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -1194,13 +1215,13 @@ declare const replySchema: z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -1213,6 +1234,9 @@ declare const replySchema: z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -1226,9 +1250,16 @@ declare const replySchema: z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -1236,12 +1267,6 @@ declare const replySchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -1268,6 +1293,12 @@ declare const replySchema: z.ZodObject<{
   } | {
     type: "leaveSpace";
   }, {
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -1318,18 +1349,9 @@ declare const replySchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -1350,13 +1372,13 @@ declare const replySchema: z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -1369,6 +1391,9 @@ declare const replySchema: z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -1382,9 +1407,16 @@ declare const replySchema: z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -1392,12 +1424,6 @@ declare const replySchema: z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -6224,6 +6250,14 @@ interface PlatformWiseActions<_ResolvedSpace extends {
     id: string;
     __platform: string;
   }) => Promise<AvatarData | undefined>;
+  getDisplayName: (ctx: {
+    client: _Client;
+    config: _Config;
+    store: Store;
+  }, space: _ResolvedSpace & {
+    id: string;
+    __platform: string;
+  }) => Promise<string | undefined>;
   getMembers: (ctx: {
     client: _Client;
     config: _Config;
@@ -6605,6 +6639,7 @@ type ReservedInstanceKeys<Def extends AnyPlatformDef> = "user" | "space" | "mess
 type InstanceActionMethods<Def extends AnyPlatformDef> = { [K in Exclude<keyof InstanceActionFns<Def>, ReservedInstanceKeys<Def> | symbol | number>]: (...args: TailArgs<Parameters<InstanceActionFns<Def>[K]>>) => ReturnType<InstanceActionFns<Def>[K]> };
 interface PlatformWiseInstanceMethods<Def extends AnyPlatformDef> {
   getAvatar: (space: PlatformSpace<Def>) => Promise<AvatarData | undefined>;
+  getDisplayName: (space: PlatformSpace<Def>) => Promise<string | undefined>;
   getMembers: (space: PlatformSpace<Def>) => Promise<PlatformUser<Def>[]>;
   getMessage: (space: PlatformSpace<Def>, messageId: string) => Promise<PlatformMessage<Def> | undefined>;
 }
@@ -6632,8 +6667,9 @@ interface SpectrumLike<Providers extends PlatformProviderConfig[] = PlatformProv
   };
   readonly __providers: Providers;
 }
+type ConfigInput<Def extends AnyPlatformDef> = z.input<Def["config"]> extends infer Input ? Input extends unknown ? { [K in keyof Input]?: Input[K] } : never : never;
 interface Platform<Def extends AnyPlatformDef> {
-  config(...args: Record<string, never> extends z.input<Def["config"]> ? [config?: z.input<Def["config"]>] : [config: z.input<Def["config"]>]): PlatformProviderConfig<Def>;
+  config(...args: Record<string, never> extends ConfigInput<Def> ? [config?: ConfigInput<Def>] : [config: ConfigInput<Def>]): PlatformProviderConfig<Def>;
   is(input: Message): input is PlatformMessage<Def>;
   is(input: Space): input is PlatformSpace<Def>;
   is(input: unknown): input is PlatformMessage<Def> | PlatformSpace<Def>;
@@ -6985,6 +7021,7 @@ declare const baseContentSchema: z.ZodDiscriminatedUnion<readonly [z.ZodObject<{
     imageSubtitle: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>>;
+  live: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodLiteral<"reaction">;
   emoji: z.ZodString;
@@ -7162,6 +7199,7 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     imageSubtitle: z.ZodOptional<z.ZodString>;
     summary: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>>;
+  live: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodLiteral<"reaction">;
   emoji: z.ZodString;
@@ -7236,6 +7274,12 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodLiteral<"reply">;
   content: z.ZodCustom<{
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -7286,18 +7330,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -7318,13 +7353,13 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -7337,6 +7372,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -7350,9 +7388,16 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -7360,12 +7405,6 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -7392,6 +7431,12 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   } | {
     type: "leaveSpace";
   }, {
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -7442,18 +7487,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -7474,13 +7510,13 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -7493,6 +7529,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -7506,9 +7545,16 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -7516,12 +7562,6 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -7552,6 +7592,12 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
   type: z.ZodLiteral<"edit">;
   content: z.ZodCustom<{
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -7602,18 +7648,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -7634,13 +7671,13 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -7653,6 +7690,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -7666,9 +7706,16 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -7676,12 +7723,6 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -7708,6 +7749,12 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   } | {
     type: "leaveSpace";
   }, {
+    type: "text";
+    text: string;
+  } | {
+    type: "markdown";
+    markdown: string;
+  } | {
     type: "attachment";
     id: string;
     name: string;
@@ -7758,18 +7805,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
     } | undefined;
     raw?: unknown;
-  } | {
-    type: "text";
-    text: string;
-  } | {
-    type: "markdown";
-    markdown: string;
   } | {
     type: "custom";
     raw: unknown;
-  } | {
-    type: "group";
-    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "poll";
     title: string;
@@ -7790,13 +7828,13 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     };
     selected: boolean;
     title: string;
+  } | {
+    type: "group";
+    items: Message<string, User, Space<unknown>>[];
   } | {
     type: "reaction";
     emoji: string;
     target: Message<string, User, Space<unknown>>;
-  } | {
-    type: "richlink";
-    url: string;
   } | {
     type: "streamText";
     stream: () => AsyncIterable<string>;
@@ -7809,6 +7847,9 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     name?: string | undefined;
     duration?: number | undefined;
     size?: number | undefined;
+  } | {
+    type: "richlink";
+    url: string;
   } | {
     type: "app";
     url: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodURL>>;
@@ -7822,9 +7863,16 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       imageSubtitle: z.ZodOptional<z.ZodString>;
       summary: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    live?: boolean | undefined;
   } | {
     type: "effect";
     content: {
+      type: "text";
+      text: string;
+    } | {
+      type: "markdown";
+      markdown: string;
+    } | {
       type: "attachment";
       id: string;
       name: string;
@@ -7832,12 +7880,6 @@ declare const contentSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       read: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>>>;
       stream: z.core.$InferOuterFunctionType<z.ZodTuple<readonly [], null>, z.ZodPromise<z.ZodCustom<ReadableStream<unknown>, ReadableStream<unknown>>>>;
       size?: number | undefined;
-    } | {
-      type: "text";
-      text: string;
-    } | {
-      type: "markdown";
-      markdown: string;
     };
     effect: string;
   } | {
@@ -7904,4 +7946,4 @@ declare function attachment(input: AttachmentInput, options?: {
   name?: string;
 }): ContentBuilder;
 //#endregion
-export { DedicatedTokenData as $, TextStreamOptions as $t, isFusorEvent as A, ContactName as An, asReply as At, PlatformUser as B, avatar as Bn, PollChoice as Bt, FusorVerify as C, asCustom as Cn, asText as Ct, WebhookRawResult as D, ContactDetails as Dn, richlink as Dt, WebhookRawRequest as E, ContactAddress as En, asRichlink as Et, PlatformInstance as F, AgentSender as Fn, renameSchema as Ft, SpaceNamespace as G, App as Gn, option as Gt, ProviderMessageRecord as H, PhotoInput as Hn, PollOption as Ht, PlatformMessage as I, User as In, Read as It, broadcast as J, app as Jn, asMarkdown as Jt, Broadcaster as K, AppLayout as Kn, poll as Kt, PlatformProviderConfig as L, Avatar as Ln, asRead as Lt, EventProducer as M, ContactPhone as Mn, replySchema as Mt, Platform as N, asContact as Nn, Rename as Nt, FusorEvent as O, ContactEmail as On, resolveContents as Ot, PlatformDef as P, contact as Pn, rename as Pt, CloudPlatform as Q, StreamTextSource as Qt, PlatformRuntime as R, AvatarData as Rn, read as Rt, FusorRespond as S, reactionSchema as Sn, typing as St, WebhookHandler as T, Contact as Tn, Richlink as Tt, ProviderUserRecord as U, buildPhotoAction as Un, asPoll as Ut, ProviderMessage as V, avatarSchema as Vn, PollChoiceInput as Vt, SchemaMessage as W, photoActionSchema as Wn, asPollOption as Wt, stream as X, DeltaExtractor as Xt, mergeStreams as Y, appLayoutSchema as Yn, markdown as Yt, Store as Z, StreamText as Zt, FusorClient as _, removeMemberSchema as _n, asVoice as _t, Content as a, edit as an, ProjectProfile as at, FusorMessagesReturn as b, asReaction as bn, unsend as bt, fromVCard as c, AddMember as cn, SlackTokenData as ct, UnsupportedKind as d, RemoveMember as dn, SubscriptionStatus as dt, Group as en, FusorTokenData as et, Spectrum as f, addMember as fn, TokenData as ft, isFusorClient as g, removeMember as gn, Voice as gt, fusor as h, leaveSpaceSchema as hn, EmojiKey as ht, attachment as i, Edit as in, ProjectData as it, AnyPlatformDef as j, ContactOrg as jn, reply as jt, fusorEvent as k, ContactInput as kn, Reply as kt, toVCard as l, LeaveSpace as ln, SpectrumCloudError as lt, definePlatform as m, leaveSpace as mn, Emoji as mt, AttachmentInput as n, group as nn, PlatformStatus as nt, ContentBuilder as o, Message as on, SharedTokenData as ot, SpectrumInstance as p, addMemberSchema as pn, cloud as pt, ManagedStream as q, AppUrl as qn, Markdown as qt, asAttachment as r, groupSchema as rn, PlatformsData as rt, ContentInput as s, Space as sn, SlackTeamMeta as st, Attachment as t, asGroup as tn, ImessageInfoData as tt, UnsupportedError as u, MemberInput as un, SubscriptionData as ut, FusorMessages as v, Reaction as vn, voice as vt, FusorVerifyRequest as w, custom as wn, text as wt, FusorReply as x, reaction as xn, Typing as xt, FusorMessagesCtx as y, ReactionBuilder as yn, Unsend as yt, PlatformSpace as z, AvatarInput as zn, Poll as zt };
+export { DedicatedTokenData as $, TextStreamOptions as $t, isFusorEvent as A, ContactName as An, asReply as At, PlatformUser as B, avatar as Bn, PollChoice as Bt, FusorVerify as C, asCustom as Cn, asText as Ct, WebhookRawResult as D, ContactDetails as Dn, richlink as Dt, WebhookRawRequest as E, ContactAddress as En, asRichlink as Et, PlatformInstance as F, AgentSender as Fn, renameSchema as Ft, SpaceNamespace as G, App as Gn, option as Gt, ProviderMessageRecord as H, PhotoInput as Hn, PollOption as Ht, PlatformMessage as I, User as In, Read as It, broadcast as J, AppUrl as Jn, asMarkdown as Jt, Broadcaster as K, AppLayout as Kn, poll as Kt, PlatformProviderConfig as L, Avatar as Ln, asRead as Lt, EventProducer as M, ContactPhone as Mn, replySchema as Mt, Platform as N, asContact as Nn, Rename as Nt, FusorEvent as O, ContactEmail as On, resolveContents as Ot, PlatformDef as P, contact as Pn, rename as Pt, CloudPlatform as Q, StreamTextSource as Qt, PlatformRuntime as R, AvatarData as Rn, read as Rt, FusorRespond as S, reactionSchema as Sn, typing as St, WebhookHandler as T, Contact as Tn, Richlink as Tt, ProviderUserRecord as U, buildPhotoAction as Un, asPoll as Ut, ProviderMessage as V, avatarSchema as Vn, PollChoiceInput as Vt, SchemaMessage as W, photoActionSchema as Wn, asPollOption as Wt, stream as X, appLayoutSchema as Xn, DeltaExtractor as Xt, mergeStreams as Y, app as Yn, markdown as Yt, Store as Z, StreamText as Zt, FusorClient as _, removeMemberSchema as _n, asVoice as _t, Content as a, edit as an, ProjectProfile as at, FusorMessagesReturn as b, asReaction as bn, unsend as bt, fromVCard as c, AddMember as cn, SlackTokenData as ct, UnsupportedKind as d, RemoveMember as dn, SubscriptionStatus as dt, Group as en, FusorTokenData as et, Spectrum as f, addMember as fn, TokenData as ft, isFusorClient as g, removeMember as gn, Voice as gt, fusor as h, leaveSpaceSchema as hn, EmojiKey as ht, attachment as i, Edit as in, ProjectData as it, AnyPlatformDef as j, ContactOrg as jn, reply as jt, fusorEvent as k, ContactInput as kn, Reply as kt, toVCard as l, LeaveSpace as ln, SpectrumCloudError as lt, definePlatform as m, leaveSpace as mn, Emoji as mt, AttachmentInput as n, group as nn, PlatformStatus as nt, ContentBuilder as o, Message as on, SharedTokenData as ot, SpectrumInstance as p, addMemberSchema as pn, cloud as pt, ManagedStream as q, AppOptions as qn, Markdown as qt, asAttachment as r, groupSchema as rn, PlatformsData as rt, ContentInput as s, Space as sn, SlackTeamMeta as st, Attachment as t, asGroup as tn, ImessageInfoData as tt, UnsupportedError as u, MemberInput as un, SubscriptionData as ut, FusorMessages as v, Reaction as vn, voice as vt, FusorVerifyRequest as w, custom as wn, text as wt, FusorReply as x, reaction as xn, Typing as xt, FusorMessagesCtx as y, ReactionBuilder as yn, Unsend as yt, PlatformSpace as z, AvatarInput as zn, Poll as zt };

package/dist/authoring.d.ts

@@ -1,4 +1,4 @@
-import { At as asReply, Cn as asCustom, Ct as asText, Et as asRichlink, Ft as renameSchema, H as ProviderMessageRecord, Hn as PhotoInput, Jt as asMarkdown, Lt as asRead, Mt as replySchema, Nn as asContact, Sn as reactionSchema, U as ProviderUserRecord, Un as buildPhotoAction, Ut as asPoll, Vn as avatarSchema, Wn as photoActionSchema, Wt as asPollOption, _n as removeMemberSchema, _t as asVoice, bn as asReaction, hn as leaveSpaceSchema, pn as addMemberSchema, q as ManagedStream, r as asAttachment, rn as groupSchema, tn as asGroup } from "./attachment-Bn3rw5jW.js";
+import { At as asReply, Cn as asCustom, Ct as asText, Et as asRichlink, Ft as renameSchema, H as ProviderMessageRecord, Hn as PhotoInput, Jt as asMarkdown, Lt as asRead, Mt as replySchema, Nn as asContact, Sn as reactionSchema, U as ProviderUserRecord, Un as buildPhotoAction, Ut as asPoll, Vn as avatarSchema, Wn as photoActionSchema, Wt as asPollOption, _n as removeMemberSchema, _t as asVoice, bn as asReaction, hn as leaveSpaceSchema, pn as addMemberSchema, q as ManagedStream, r as asAttachment, rn as groupSchema, tn as asGroup } from "./attachment-BpPKbxT1.js";
 import z from "zod";
 import { FetchSpanOptions, LogAttrs, LogAttrs as LogAttrs$1, LogLevel, PhotonLogger, SanitizeUrlOptions, createLogger, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel } from "@photon-ai/otel";
 import { Token } from "marked";
@@ -30,6 +30,61 @@ declare const ensureM4a: (buffer: Buffer, mimeType: string) => Promise<{
   duration?: number;
 }>;
 //#endregion
+//#region src/utils/env.d.ts
+/**
+ * Build a Spectrum config env-var name from a channel and a key, centralizing
+ * the `SPECTRUM_<CHANNEL>_<KEY>` convention so the prefix can't drift or be
+ * mistyped per field. Both segments are joined verbatim (callers pass them
+ * already upper-snake-cased), e.g. `envFor("TELEGRAM", "BOT_TOKEN")` →
+ * `"SPECTRUM_TELEGRAM_BOT_TOKEN"`.
+ */
+declare const envFor: (channel: string, key: string) => string;
+/**
+ * Wrap a config-field schema so it falls back to an environment variable when
+ * the field is omitted. Precedence is **explicit value > env var > the inner
+ * schema's own default/required check**:
+ *
+ * - An explicit value (anything other than `undefined`) is passed straight
+ *   through — a caller-supplied config always wins over the environment.
+ * - When the field is `undefined`, `process.env[envKey]` is substituted. An
+ *   env var set to the empty string is treated as unset (a common deploy
+ *   footgun) so it doesn't satisfy a `.min(1)` by accident.
+ * - The inner `schema` then validates the resolved value, keeping its exact
+ *   semantics — regex, `.min(1)`, `.url()`, `.optional()`, `.default(...)`.
+ *   When both the field and the env var are absent, a required inner schema
+ *   raises its normal "required" error.
+ *
+ * The output type is the inner schema's output type, so call sites are
+ * unchanged. Because substitution only happens on `undefined`, wrapping a
+ * field inside a `z.object` leaves it a plain key on the parsed result — union
+ * discriminators like `"accessToken" in config` keep working.
+ *
+ * @example
+ * ```ts
+ * botToken: fromEnv("SPECTRUM_TELEGRAM_BOT_TOKEN", z.string().regex(BOT_TOKEN_PATTERN)),
+ * ```
+ */
+declare const fromEnv: <T extends z.ZodType>(envKey: string, schema: T) => z.ZodPreprocess<T>;
+/**
+ * Rewrite a platform's config schema so every string-leaf field falls back to
+ * `SPECTRUM_<PLATFORM>_<KEY>` when omitted which is the equivalent of
+ * hand-wrapping each field with {@link fromEnv}. Called once by
+ * `definePlatform`, so adapters declare plain Zod and get env fallback for free.
+ *
+ * - **object**: each string-leaf field is wrapped with `fromEnv`; non-string
+ *   fields (records, arrays, nested objects, booleans, numbers) are left as-is.
+ *   The object is only reconstructed when a field actually changed, and
+ *   `.strict()` is preserved so an empty strict "cloud" branch is untouched.
+ * - **union**: each option is rewritten independently, so an env value only
+ *   satisfies the branch that declares that field (a direct/cloud union stays
+ *   correctly discriminated).
+ * - anything else is returned unchanged.
+ *
+ * The output type is identical to the input schema's. Only omitted fields gain
+ * an env fallback which means that `z.infer` and downstream contexts are unaffected.
+ */
+declare const envAwareConfig: <T extends z.ZodType>(name: string, schema: T) => T;
+//#endregion
 //#region src/utils/instrumented-fetch.d.ts
 /**
  * Build a fetch that traces spectrum's OWN outbound HTTP: each request through
@@ -123,4 +178,4 @@ declare const resumableOrderedStream: <TLive, TMissed, TOutput>(options: Resumab
  */
 declare function errorAttrs(error: unknown, prefix?: string): LogAttrs$1;
 //#endregion
-export { type CloseableAsyncIterable, type LogAttrs, type LogLevel, type PhotoInput, type PhotonLogger, type ProviderMessageRecord, type ProviderUserRecord, type ResumableStreamItem, type SanitizeUrlOptions, addMemberSchema, asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asReply, asRichlink, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, renderInlineTokens, replySchema, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel, tracedFetch };
+export { type CloseableAsyncIterable, type LogAttrs, type LogLevel, type PhotoInput, type PhotonLogger, type ProviderMessageRecord, type ProviderUserRecord, type ResumableStreamItem, type SanitizeUrlOptions, addMemberSchema, asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asReply, asRichlink, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, ensureM4a, envAwareConfig, envFor, errorAttrs, fromEnv, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, renderInlineTokens, replySchema, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel, tracedFetch };

package/dist/authoring.js

@@ -1,4 +1,4 @@
-import { A as addMemberSchema, B as groupSchema, E as asPollOption, F as asMarkdown, H as asText, L as markdownSchema, M as leaveSpaceSchema, P as removeMemberSchema, R as asGroup, S as asReaction, T as asPoll, W as textSchema, Y as asContact, _ as replySchema, at as attachmentSchema, b as asRead, d as asVoice, et as avatarSchema, h as asReply, i as stream, l as renderInlineTokens, nt as photoActionSchema, o as errorAttrs, p as asRichlink, q as asCustom, rt as asAttachment, st as tracedFetch, tt as buildPhotoAction, w as reactionSchema, y as renameSchema } from "./stream-DxI5ZiE2.js";
+import { B as markdownSchema, C as asRead, D as reactionSchema, F as leaveSpaceSchema, G as asText, L as removeMemberSchema, N as addMemberSchema, O as asPoll, Q as asContact, R as asMarkdown, S as renameSchema, T as asReaction, U as groupSchema, V as asGroup, X as asCustom, at as photoActionSchema, b as replySchema, ct as attachmentSchema, d as envAwareConfig, f as envFor, g as asRichlink, i as stream, it as buildPhotoAction, k as asPollOption, l as renderInlineTokens, m as asVoice, o as errorAttrs, ot as asAttachment, p as fromEnv, q as textSchema, rt as avatarSchema, ut as tracedFetch, v as asReply } from "./stream-DAfZ5DFR.js";
 import z from "zod";
 import { createLogger, createLogger as createLogger$1, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel } from "@photon-ai/otel";
 import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
@@ -422,4 +422,4 @@ const resumableOrderedStream = (options) => stream((emit, end) => {
 	};
 });
 //#endregion
-export { addMemberSchema, asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asReply, asRichlink, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, ensureM4a, errorAttrs, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, renderInlineTokens, replySchema, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel, tracedFetch };
+export { addMemberSchema, asAttachment, asContact, asCustom, asGroup, asMarkdown, asPoll, asPollOption, asReaction, asRead, asReply, asRichlink, asText, asVoice, avatarSchema, buildPhotoAction, createLogger, ensureM4a, envAwareConfig, envFor, errorAttrs, fromEnv, groupSchema, leaveSpaceSchema, messageEffectSchema, photoActionSchema, reactionSchema, removeMemberSchema, renameSchema, renderInlineTokens, replySchema, resumableOrderedStream, sanitizeEmail, sanitizeErrorMessage, sanitizePhone, sanitizeUrl, setLogLevel, tracedFetch };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { $ as DedicatedTokenData, $t as TextStreamOptions, A as isFusorEvent, An as ContactName, B as PlatformUser, Bn as avatar, Bt as PollChoice, C as FusorVerify, D as WebhookRawResult, Dn as ContactDetails, Dt as richlink, E as WebhookRawRequest, En as ContactAddress, F as PlatformInstance, Fn as AgentSender, G as SpaceNamespace, Gn as App, Gt as option, Ht as PollOption, I as PlatformMessage, In as User, It as Read, J as broadcast, Jn as app, K as Broadcaster, Kn as AppLayout, Kt as poll, L as PlatformProviderConfig, Ln as Avatar, M as EventProducer, Mn as ContactPhone, N as Platform, Nt as Rename, O as FusorEvent, On as ContactEmail, Ot as resolveContents, P as PlatformDef, Pn as contact, Pt as rename, Q as CloudPlatform, Qt as StreamTextSource, R as PlatformRuntime, Rn as AvatarData, Rt as read, S as FusorRespond, St as typing, T as WebhookHandler, Tn as Contact, Tt as Richlink, V as ProviderMessage, Vt as PollChoiceInput, W as SchemaMessage, X as stream, Xt as DeltaExtractor, Y as mergeStreams, Yn as appLayoutSchema, Yt as markdown, Z as Store, Zt as StreamText, _ as FusorClient, a as Content, an as edit, at as ProjectProfile, b as FusorMessagesReturn, bt as unsend, c as fromVCard, cn as AddMember, ct as SlackTokenData, d as UnsupportedKind, dn as RemoveMember, dt as SubscriptionStatus, en as Group, et as FusorTokenData, f as Spectrum, fn as addMember, ft as TokenData, g as isFusorClient, gn as removeMember, gt as Voice, h as fusor, ht as EmojiKey, i as attachment, in as Edit, it as ProjectData, j as AnyPlatformDef, jn as ContactOrg, jt as reply, k as fusorEvent, kn as ContactInput, kt as Reply, l as toVCard, ln as LeaveSpace, lt as SpectrumCloudError, m as definePlatform, mn as leaveSpace, mt as Emoji, n as AttachmentInput, nn as group, nt as PlatformStatus, o as ContentBuilder, on as Message, ot as SharedTokenData, p as SpectrumInstance, pt as cloud, q as ManagedStream, qn as AppUrl, qt as Markdown, rt as PlatformsData, s as ContentInput, sn as Space, st as SlackTeamMeta, t as Attachment, tt as ImessageInfoData, u as UnsupportedError, un as MemberInput, ut as SubscriptionData, v as FusorMessages, vn as Reaction, vt as voice, w as FusorVerifyRequest, wn as custom, wt as text, x as FusorReply, xn as reaction, xt as Typing, y as FusorMessagesCtx, yn as ReactionBuilder, yt as Unsend, z as PlatformSpace, zn as AvatarInput, zt as Poll } from "./attachment-Bn3rw5jW.js";
-export { type AddMember, type AgentSender, type AnyPlatformDef, type App, type AppLayout, type AppUrl, type Attachment, type AttachmentInput, type Avatar, type AvatarData, type AvatarInput, type Broadcaster, type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, type Content, type ContentBuilder, type ContentInput, type DedicatedTokenData, type DeltaExtractor, type Edit, Emoji, type EmojiKey, type EventProducer, type FusorClient, type FusorEvent, type FusorMessages, type FusorMessagesCtx, type FusorMessagesReturn, type FusorReply, type FusorRespond, type FusorTokenData, type FusorVerify, type FusorVerifyRequest, type Group, type ImessageInfoData, type LeaveSpace, type ManagedStream, type Markdown, type MemberInput, type Message, type Platform, type PlatformDef, type PlatformInstance, type PlatformMessage, type PlatformProviderConfig, type PlatformRuntime, type PlatformSpace, type PlatformStatus, type PlatformUser, type PlatformsData, type Poll, type PollChoice, type PollChoiceInput, type PollOption, type ProjectData, type ProjectProfile, type ProviderMessage, type Reaction, type ReactionBuilder, type Read, type RemoveMember, type Rename, type Reply, type Richlink, type SchemaMessage, type SharedTokenData, type SlackTeamMeta, type SlackTokenData, type Space, type SpaceNamespace, Spectrum, SpectrumCloudError, type SpectrumInstance, type Store, type StreamText, type StreamTextSource, type SubscriptionData, type SubscriptionStatus, type TextStreamOptions, type TokenData, type Typing, type Unsend, UnsupportedError, type UnsupportedKind, type User, type Voice, type WebhookHandler, type WebhookRawRequest, type WebhookRawResult, addMember, app, appLayoutSchema, attachment, avatar, broadcast, cloud, contact, custom, definePlatform, edit, fromVCard, fusor, fusorEvent, group, isFusorClient, isFusorEvent, leaveSpace, markdown, mergeStreams, option, poll, reaction, read, removeMember, rename, reply, resolveContents, richlink, stream, text, toVCard, typing, unsend, voice };
+import { $ as DedicatedTokenData, $t as TextStreamOptions, A as isFusorEvent, An as ContactName, B as PlatformUser, Bn as avatar, Bt as PollChoice, C as FusorVerify, D as WebhookRawResult, Dn as ContactDetails, Dt as richlink, E as WebhookRawRequest, En as ContactAddress, F as PlatformInstance, Fn as AgentSender, G as SpaceNamespace, Gn as App, Gt as option, Ht as PollOption, I as PlatformMessage, In as User, It as Read, J as broadcast, Jn as AppUrl, K as Broadcaster, Kn as AppLayout, Kt as poll, L as PlatformProviderConfig, Ln as Avatar, M as EventProducer, Mn as ContactPhone, N as Platform, Nt as Rename, O as FusorEvent, On as ContactEmail, Ot as resolveContents, P as PlatformDef, Pn as contact, Pt as rename, Q as CloudPlatform, Qt as StreamTextSource, R as PlatformRuntime, Rn as AvatarData, Rt as read, S as FusorRespond, St as typing, T as WebhookHandler, Tn as Contact, Tt as Richlink, V as ProviderMessage, Vt as PollChoiceInput, W as SchemaMessage, X as stream, Xn as appLayoutSchema, Xt as DeltaExtractor, Y as mergeStreams, Yn as app, Yt as markdown, Z as Store, Zt as StreamText, _ as FusorClient, a as Content, an as edit, at as ProjectProfile, b as FusorMessagesReturn, bt as unsend, c as fromVCard, cn as AddMember, ct as SlackTokenData, d as UnsupportedKind, dn as RemoveMember, dt as SubscriptionStatus, en as Group, et as FusorTokenData, f as Spectrum, fn as addMember, ft as TokenData, g as isFusorClient, gn as removeMember, gt as Voice, h as fusor, ht as EmojiKey, i as attachment, in as Edit, it as ProjectData, j as AnyPlatformDef, jn as ContactOrg, jt as reply, k as fusorEvent, kn as ContactInput, kt as Reply, l as toVCard, ln as LeaveSpace, lt as SpectrumCloudError, m as definePlatform, mn as leaveSpace, mt as Emoji, n as AttachmentInput, nn as group, nt as PlatformStatus, o as ContentBuilder, on as Message, ot as SharedTokenData, p as SpectrumInstance, pt as cloud, q as ManagedStream, qn as AppOptions, qt as Markdown, rt as PlatformsData, s as ContentInput, sn as Space, st as SlackTeamMeta, t as Attachment, tt as ImessageInfoData, u as UnsupportedError, un as MemberInput, ut as SubscriptionData, v as FusorMessages, vn as Reaction, vt as voice, w as FusorVerifyRequest, wn as custom, wt as text, x as FusorReply, xn as reaction, xt as Typing, y as FusorMessagesCtx, yn as ReactionBuilder, yt as Unsend, z as PlatformSpace, zn as AvatarInput, zt as Poll } from "./attachment-BpPKbxT1.js";
+export { type AddMember, type AgentSender, type AnyPlatformDef, type App, type AppLayout, type AppOptions, type AppUrl, type Attachment, type AttachmentInput, type Avatar, type AvatarData, type AvatarInput, type Broadcaster, type CloudPlatform, type Contact, type ContactAddress, type ContactDetails, type ContactEmail, type ContactInput, type ContactName, type ContactOrg, type ContactPhone, type Content, type ContentBuilder, type ContentInput, type DedicatedTokenData, type DeltaExtractor, type Edit, Emoji, type EmojiKey, type EventProducer, type FusorClient, type FusorEvent, type FusorMessages, type FusorMessagesCtx, type FusorMessagesReturn, type FusorReply, type FusorRespond, type FusorTokenData, type FusorVerify, type FusorVerifyRequest, type Group, type ImessageInfoData, type LeaveSpace, type ManagedStream, type Markdown, type MemberInput, type Message, type Platform, type PlatformDef, type PlatformInstance, type PlatformMessage, type PlatformProviderConfig, type PlatformRuntime, type PlatformSpace, type PlatformStatus, type PlatformUser, type PlatformsData, type Poll, type PollChoice, type PollChoiceInput, type PollOption, type ProjectData, type ProjectProfile, type ProviderMessage, type Reaction, type ReactionBuilder, type Read, type RemoveMember, type Rename, type Reply, type Richlink, type SchemaMessage, type SharedTokenData, type SlackTeamMeta, type SlackTokenData, type Space, type SpaceNamespace, Spectrum, SpectrumCloudError, type SpectrumInstance, type Store, type StreamText, type StreamTextSource, type SubscriptionData, type SubscriptionStatus, type TextStreamOptions, type TokenData, type Typing, type Unsend, UnsupportedError, type UnsupportedKind, type User, type Voice, type WebhookHandler, type WebhookRawRequest, type WebhookRawResult, addMember, app, appLayoutSchema, attachment, avatar, broadcast, cloud, contact, custom, definePlatform, edit, fromVCard, fusor, fusorEvent, group, isFusorClient, isFusorEvent, leaveSpace, markdown, mergeStreams, option, poll, reaction, read, removeMember, rename, reply, resolveContents, richlink, stream, text, toVCard, typing, unsend, voice };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as avatar, A as addMemberSchema, C as reaction, D as option, F as asMarkdown, G as StreamConsumedError, H as asText, I as markdown, J as custom, K as drainStreamText, M as leaveSpaceSchema, N as removeMember, O as poll, P as removeMemberSchema, Q as toVCard, U as text, V as resolveContents, X as contact, Y as asContact, Z as fromVCard, a as contentAttrs, c as markdownToPlainText, et as avatarSchema, f as voice, g as reply, i as stream, it as attachment, j as leaveSpace, k as addMember, m as richlink, n as createAsyncQueue, o as errorAttrs, ot as fetchUrlBytes, q as asCustom, r as mergeStreams, rt as asAttachment, s as senderAttrs, st as tracedFetch, t as broadcast, u as classifyIdentifier, v as rename, x as read, y as renameSchema, z as group } from "./stream-DxI5ZiE2.js";
+import { $ as contact, A as option, E as reaction, F as leaveSpaceSchema, G as asText, H as group, I as removeMember, J as StreamConsumedError, K as text, L as removeMemberSchema, M as addMember, N as addMemberSchema, P as leaveSpace, Q as asContact, R as asMarkdown, S as renameSchema, W as resolveContents, X as asCustom, Y as drainStreamText, Z as custom, _ as richlink, a as contentAttrs, c as markdownToPlainText, d as envAwareConfig, et as fromVCard, f as envFor, h as voice, i as stream, j as poll, lt as fetchUrlBytes, n as createAsyncQueue, nt as avatar, o as errorAttrs, ot as asAttachment, r as mergeStreams, rt as avatarSchema, s as senderAttrs, st as attachment, t as broadcast, tt as toVCard, u as classifyIdentifier, ut as tracedFetch, w as read, x as rename, y as reply, z as markdown } from "./stream-DAfZ5DFR.js";
 import z from "zod";
 import ogs from "open-graph-scraper";
 import { createLogger, setLogLevel, setupOtel, withSpan } from "@photon-ai/otel";
@@ -89,7 +89,8 @@ const layoutAccessor = z.function({
 const appSchema = z.object({
 	type: z.literal("app"),
 	url: urlAccessor,
-	layout: layoutAccessor
+	layout: layoutAccessor,
+	live: z.boolean().optional()
 });
 const memoize = (factory) => {
 	let cached;
@@ -136,7 +137,7 @@ const buildLayout = (metadata, url, image) => {
 * across `url()` / `layout()`; fetch / parse failures resolve to a host-only
 * caption (no throw, no retry).
 */
-const asApp = (url) => {
+const asApp = (url, options = {}) => {
 	const getUrl = resolveUrl(url);
 	const getMetadata = memoize(async () => fetchLinkMetadata(await getUrl()));
 	const getLayout = memoize(async () => {
@@ -154,11 +155,18 @@ const asApp = (url) => {
 	return appSchema.parse({
 		type: "app",
 		url: getUrl,
-		layout: getLayout
+		layout: getLayout,
+		...options
 	});
 };
-function app(url) {
-	return { build: async () => asApp(url) };
+/**
+* Construct an app card from a URL.
+*
+* Pass `{ live: true }` to ask supported platforms to render the installed
+* app extension's live UI. Other platforms retain their normal URL fallback.
+*/
+function app(url, options = {}) {
+	return { build: async () => asApp(url, options) };
 }
 //#endregion
 //#region src/content/edit.ts
@@ -2313,6 +2321,7 @@ const RESERVED_SPACE_KEYS = new Set([
 	"getMessage",
 	"getMembers",
 	"getAvatar",
+	"getDisplayName",
 	"rename",
 	"avatar",
 	"add",
@@ -2325,7 +2334,8 @@ const RESERVED_SPACE_KEYS = new Set([
 const PLATFORM_WISE_ACTION_KEYS = new Set([
 	"getMessage",
 	"getMembers",
-	"getAvatar"
+	"getAvatar",
+	"getDisplayName"
 ]);
 const RESERVED_MESSAGE_KEYS = new Set([
 	"content",
@@ -2687,6 +2697,18 @@ function buildSpace(params) {
 			store
 		}, spaceRef));
 	}
+	async function getDisplayNameImpl() {
+		const getDisplayName = definition.actions?.getDisplayName;
+		if (!getDisplayName) throw UnsupportedError.action("getDisplayName", definition.name);
+		return withSpan("spectrum.space.displayName.get", {
+			"spectrum.provider": definition.name,
+			"spectrum.space.id": spaceRef.id
+		}, async () => await getDisplayName({
+			client,
+			config,
+			store
+		}, spaceRef));
+	}
 	const platformActions = {};
 	const declaredActions = definition.space.actions;
 	if (declaredActions) for (const [name, factory] of Object.entries(declaredActions)) {
@@ -2715,6 +2737,7 @@ function buildSpace(params) {
 		getMessage: getMessageImpl,
 		getMembers: getMembersImpl,
 		getAvatar: getAvatarImpl,
+		getDisplayName: getDisplayNameImpl,
 		rename: async (displayName) => {
 			await space.send(rename(displayName));
 		},
@@ -2975,7 +2998,8 @@ function definePlatform(name, rawDef) {
 	const def = rawDef;
 	const fullDef = {
 		...def,
-		name
+		name,
+		config: envAwareConfig(name, def.config)
 	};
 	const platformCache = /* @__PURE__ */ new WeakMap();
 	const narrowSpectrum = (spectrum) => {
@@ -3027,7 +3051,7 @@ function definePlatform(name, rawDef) {
 }
 //#endregion
 //#region src/build-env.ts
-const SPECTRUM_SDK_VERSION = "9.0.0";
+const SPECTRUM_SDK_VERSION = "9.3.0";
 //#endregion
 //#region src/utils/provider-packages.ts
 const OFFICIAL_PROVIDER_PACKAGES = {
@@ -4067,12 +4091,27 @@ function bootstrapTelemetry(opts) {
 function applyLogLevel(level) {
 	if (level) setLogLevel(level);
 }
+function envValue(key) {
+	const value = process.env[key];
+	return value === "" ? void 0 : value;
+}
+function resolveProjectCredentials(options) {
+	return {
+		projectId: options.projectId ?? envValue(envFor("PROJECT", "ID")),
+		projectSecret: options.projectSecret ?? envValue(envFor("PROJECT", "SECRET"))
+	};
+}
 async function Spectrum(options) {
-	spectrumConfigSchema.parse(options);
-	const { projectId, projectSecret, providers, options: runtimeOptions, telemetry, webhookSecret } = options;
+	const { projectId, projectSecret } = resolveProjectCredentials(options);
+	spectrumConfigSchema.parse({
+		...options,
+		projectId,
+		projectSecret
+	});
+	const { providers, options: runtimeOptions, telemetry, webhookSecret } = options;
 	const flattenGroups = runtimeOptions?.flattenGroups ?? false;
 	applyLogLevel(runtimeOptions?.logLevel);
-	const resolvedWebhookSecret = webhookSecret ?? process.env.SPECTRUM_WEBHOOK_SECRET;
+	const resolvedWebhookSecret = webhookSecret ?? process.env[envFor("WEBHOOK", "SECRET")];
 	const otelHandle = telemetry ? bootstrapTelemetry({
 		projectId,
 		projectSecret

package/dist/{stream-DxI5ZiE2.js → stream-DAfZ5DFR.js}

@@ -1158,6 +1158,128 @@ function voice(input, options) {
 	} };
 }
 //#endregion
+//#region src/utils/env.ts
+/**
+* Build a Spectrum config env-var name from a channel and a key, centralizing
+* the `SPECTRUM_<CHANNEL>_<KEY>` convention so the prefix can't drift or be
+* mistyped per field. Both segments are joined verbatim (callers pass them
+* already upper-snake-cased), e.g. `envFor("TELEGRAM", "BOT_TOKEN")` →
+* `"SPECTRUM_TELEGRAM_BOT_TOKEN"`.
+*/
+const envFor = (channel, key) => `SPECTRUM_${channel}_${key}`;
+/**
+* Wrap a config-field schema so it falls back to an environment variable when
+* the field is omitted. Precedence is **explicit value > env var > the inner
+* schema's own default/required check**:
+*
+* - An explicit value (anything other than `undefined`) is passed straight
+*   through — a caller-supplied config always wins over the environment.
+* - When the field is `undefined`, `process.env[envKey]` is substituted. An
+*   env var set to the empty string is treated as unset (a common deploy
+*   footgun) so it doesn't satisfy a `.min(1)` by accident.
+* - The inner `schema` then validates the resolved value, keeping its exact
+*   semantics — regex, `.min(1)`, `.url()`, `.optional()`, `.default(...)`.
+*   When both the field and the env var are absent, a required inner schema
+*   raises its normal "required" error.
+*
+* The output type is the inner schema's output type, so call sites are
+* unchanged. Because substitution only happens on `undefined`, wrapping a
+* field inside a `z.object` leaves it a plain key on the parsed result — union
+* discriminators like `"accessToken" in config` keep working.
+*
+* @example
+* ```ts
+* botToken: fromEnv("SPECTRUM_TELEGRAM_BOT_TOKEN", z.string().regex(BOT_TOKEN_PATTERN)),
+* ```
+*/
+const fromEnv = (envKey, schema) => z.preprocess((value) => {
+	if (value !== void 0) return value;
+	const envValue = process.env[envKey];
+	return envValue === "" ? void 0 : envValue;
+}, schema);
+/**
+* Normalize a platform id into the env-var prefix segment: upper-case, with any
+* run of non-alphanumeric characters collapsed to a single `_`. This is a
+* whole-name transform, NOT camelCase splitting, so it reproduces the prefixes
+* the adapters used by hand — `"telegram"` → `TELEGRAM`,
+* `"WhatsApp Business"` → `WHATSAPP_BUSINESS`, `"Slack"` → `SLACK`.
+*/
+const NON_ALPHANUMERIC_RUN = /[^A-Z0-9]+/;
+const normalizePlatformName = (name) => name.toUpperCase().split(NON_ALPHANUMERIC_RUN).filter(Boolean).join("_");
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+/** Convert a camelCase config field name into its UPPER_SNAKE env-var suffix. */
+const toEnvKey = (field) => field.replace(CAMEL_BOUNDARY, "$1_$2").toUpperCase();
+const INNER_TYPE_WRAPPERS = new Set([
+	"optional",
+	"nullable",
+	"default",
+	"readonly",
+	"catch",
+	"nonoptional",
+	"prefault"
+]);
+const asInternal = (schema) => schema;
+const unwrapSchema = (schema) => {
+	let current = asInternal(schema);
+	for (let depth = 0; depth < 20; depth++) {
+		const { type } = current.def;
+		if (INNER_TYPE_WRAPPERS.has(type) && current.def.innerType) {
+			current = current.def.innerType;
+			continue;
+		}
+		if (type === "pipe" && (current.def.out || current.def.in)) {
+			current = current.def.out ?? current.def.in;
+			continue;
+		}
+		break;
+	}
+	return current;
+};
+const isStringLeaf = (schema) => unwrapSchema(schema).def.type === "string";
+const isStrictObject = (def) => def.catchall?.def.type === "never";
+/**
+* Rewrite a platform's config schema so every string-leaf field falls back to
+* `SPECTRUM_<PLATFORM>_<KEY>` when omitted which is the equivalent of
+* hand-wrapping each field with {@link fromEnv}. Called once by
+* `definePlatform`, so adapters declare plain Zod and get env fallback for free.
+*
+* - **object**: each string-leaf field is wrapped with `fromEnv`; non-string
+*   fields (records, arrays, nested objects, booleans, numbers) are left as-is.
+*   The object is only reconstructed when a field actually changed, and
+*   `.strict()` is preserved so an empty strict "cloud" branch is untouched.
+* - **union**: each option is rewritten independently, so an env value only
+*   satisfies the branch that declares that field (a direct/cloud union stays
+*   correctly discriminated).
+* - anything else is returned unchanged.
+*
+* The output type is identical to the input schema's. Only omitted fields gain
+* an env fallback which means that `z.infer` and downstream contexts are unaffected.
+*/
+const envAwareConfig = (name, schema) => {
+	return rewrite(`SPECTRUM_${normalizePlatformName(name)}`, schema);
+};
+const rewrite = (prefix, schema) => {
+	const { def } = asInternal(schema);
+	if (def.type === "object" && def.shape) return rewriteObject(prefix, def, schema);
+	if (def.type === "union" && def.options) {
+		const options = def.options.map((option) => rewrite(prefix, option));
+		return z.union(options);
+	}
+	return schema;
+};
+const rewriteObject = (prefix, def, original) => {
+	const shape = def.shape;
+	const nextShape = {};
+	let changed = false;
+	for (const [key, field] of Object.entries(shape)) if (isStringLeaf(field)) {
+		nextShape[key] = fromEnv(`${prefix}_${toEnvKey(key)}`, field);
+		changed = true;
+	} else nextShape[key] = field;
+	if (!changed) return original;
+	const rebuilt = z.object(nextShape);
+	return isStrictObject(def) ? rebuilt.strict() : rebuilt;
+};
+//#endregion
 //#region src/utils/identifier.ts
 const PHONE_LIKE = /^\+?[\d\s()\-.]{7,}$/;
 const EMAIL_LIKE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -1576,4 +1698,4 @@ function broadcast(source) {
 	};
 }
 //#endregion
-export { avatar as $, addMemberSchema as A, groupSchema as B, reaction as C, option as D, asPollOption as E, asMarkdown as F, StreamConsumedError as G, asText as H, markdown as I, custom as J, drainStreamText as K, markdownSchema as L, leaveSpaceSchema as M, removeMember as N, poll as O, removeMemberSchema as P, toVCard as Q, asGroup as R, asReaction as S, asPoll as T, text as U, resolveContents as V, textSchema as W, contact as X, asContact as Y, fromVCard as Z, replySchema as _, contentAttrs as a, attachmentSchema as at, asRead as b, markdownToPlainText as c, asVoice as d, avatarSchema as et, voice as f, reply as g, asReply as h, stream as i, attachment as it, leaveSpace as j, addMember as k, renderInlineTokens as l, richlink as m, createAsyncQueue as n, photoActionSchema as nt, errorAttrs as o, fetchUrlBytes as ot, asRichlink as p, asCustom as q, mergeStreams as r, asAttachment as rt, senderAttrs as s, tracedFetch as st, broadcast as t, buildPhotoAction as tt, classifyIdentifier as u, rename as v, reactionSchema as w, read as x, renameSchema as y, group as z };
+export { contact as $, option as A, markdownSchema as B, asRead as C, reactionSchema as D, reaction as E, leaveSpaceSchema as F, asText as G, group as H, removeMember as I, StreamConsumedError as J, text as K, removeMemberSchema as L, addMember as M, addMemberSchema as N, asPoll as O, leaveSpace as P, asContact as Q, asMarkdown as R, renameSchema as S, asReaction as T, groupSchema as U, asGroup as V, resolveContents as W, asCustom as X, drainStreamText as Y, custom as Z, richlink as _, contentAttrs as a, photoActionSchema as at, replySchema as b, markdownToPlainText as c, attachmentSchema as ct, envAwareConfig as d, fromVCard as et, envFor as f, asRichlink as g, voice as h, stream as i, buildPhotoAction as it, poll as j, asPollOption as k, renderInlineTokens as l, fetchUrlBytes as lt, asVoice as m, createAsyncQueue as n, avatar as nt, errorAttrs as o, asAttachment as ot, fromEnv as p, textSchema as q, mergeStreams as r, avatarSchema as rt, senderAttrs as s, attachment as st, broadcast as t, toVCard as tt, classifyIdentifier as u, tracedFetch as ut, asReply as v, read as w, rename as x, reply as y, markdown as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrum-ts/core",
-  "version": "9.0.0",
+  "version": "9.3.0",
   "description": "The spectrum-ts runtime — Spectrum, content builders, fusor, and the provider authoring API.",
   "repository": {
     "type": "git",