@spectrum-ts/core 9.1.0 → 9.3.1

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-B4H1Q8xO.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-ChqzKngn.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-B4H1Q8xO.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-ChqzKngn.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
@@ -2990,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) => {
@@ -3042,7 +3051,7 @@ function definePlatform(name, rawDef) {
 }
 //#endregion
 //#region src/build-env.ts
-const SPECTRUM_SDK_VERSION = "9.1.0";
+const SPECTRUM_SDK_VERSION = "9.3.1";
 //#endregion
 //#region src/utils/provider-packages.ts
 const OFFICIAL_PROVIDER_PACKAGES = {
@@ -4082,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.1.0",
+  "version": "9.3.1",
   "description": "The spectrum-ts runtime — Spectrum, content builders, fusor, and the provider authoring API.",
   "repository": {
     "type": "git",