@promptbook/javascript 0.111.0-7 → 0.112.0-11

package/umd/src/utils/chat/chatAttachments/appendChatAttachmentContext.d.ts

@@ -0,0 +1,10 @@
+import type { ChatAttachment } from '../chatAttachments';
+/**
+ * Appends attachment metadata context to message content so chat models can see uploaded file URLs.
+ *
+ * @param {string} messageContent - The original message content.
+ * @param {ReadonlyArray<ChatAttachment>} attachments - The attachments to append.
+ * @returns {string} The updated message content.
+ * @public exported from `@promptbook/core`
+ */
+export declare function appendChatAttachmentContext(messageContent: string, attachments: ReadonlyArray<ChatAttachment>): string;

package/umd/src/utils/chat/chatAttachments/appendChatAttachmentContextWithContent.d.ts

@@ -0,0 +1,14 @@
+import type { ChatAttachment, ResolveChatAttachmentOptions } from '../chatAttachments';
+/**
+ * Appends attachment metadata and inline attachment content to message content.
+ *
+ * The helper never throws because attachment downloads are best-effort and should
+ * not block chat requests.
+ *
+ * @param {string} messageContent - The original message content.
+ * @param {ReadonlyArray<ChatAttachment>} attachments - The attachments to append.
+ * @param {ResolveChatAttachmentOptions} options - Options for resolution.
+ * @returns {Promise<string>} The updated message content.
+ * @public exported from `@promptbook/core`
+ */
+export declare function appendChatAttachmentContextWithContent(messageContent: string, attachments: ReadonlyArray<ChatAttachment>, options?: ResolveChatAttachmentOptions): Promise<string>;

package/umd/src/utils/chat/chatAttachments/appendChatContextSections.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Appends one or more context sections to message content.
+ *
+ * @private function of appendChatAttachmentContext
+ */
+export declare function appendChatContextSections(messageContent: string, contextSections: ReadonlyArray<string>): string;

package/umd/src/utils/chat/chatAttachments/formatChatAttachmentContentContext.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedChatAttachmentContent } from '../chatAttachments';
+/**
+ * Formats inline attachment-content context section for the model.
+ *
+ * @param {ReadonlyArray<ResolvedChatAttachmentContent>} resolvedContents - The resolved contents to format.
+ * @returns {string} The formatted context.
+ * @public exported from `@promptbook/core`
+ */
+export declare function formatChatAttachmentContentContext(resolvedContents: ReadonlyArray<ResolvedChatAttachmentContent>): string;

package/umd/src/utils/chat/chatAttachments/formatChatAttachmentContext.d.ts

@@ -0,0 +1,9 @@
+import type { ChatAttachment } from '../chatAttachments';
+/**
+ * Builds a markdown section that lists attachment URLs for the model.
+ *
+ * @param {ReadonlyArray<ChatAttachment>} attachments - The attachments to format.
+ * @returns {string} The formatted context.
+ * @public exported from `@promptbook/core`
+ */
+export declare function formatChatAttachmentContext(attachments: ReadonlyArray<ChatAttachment>): string;

package/umd/src/utils/chat/chatAttachments/normalizeChatAttachments.d.ts

@@ -0,0 +1,11 @@
+import type { ChatAttachment } from '../chatAttachments';
+/**
+ * Normalizes a potentially invalid attachments payload from the client request.
+ *
+ * Invalid items are skipped and duplicate URLs are de-duplicated.
+ *
+ * @param {unknown} rawAttachments - The raw attachments to normalize.
+ * @returns {Array<ChatAttachment>} The normalized attachments.
+ * @public exported from `@promptbook/core`
+ */
+export declare function normalizeChatAttachments(rawAttachments: unknown): Array<ChatAttachment>;

package/umd/src/utils/chat/chatAttachments/resolveChatAttachmentContent.d.ts

@@ -0,0 +1,11 @@
+import type { ChatAttachment, ResolveChatAttachmentOptions, ResolvedChatAttachmentContent } from '../chatAttachments';
+/**
+ * Downloads and resolves one attachment into inline text context when possible.
+ *
+ * @param {ChatAttachment} attachment - The attachment to resolve.
+ * @param {number} maxInlineCharacters - Maximum number of characters to inline.
+ * @param {ResolveChatAttachmentOptions} options - Options for resolution.
+ * @returns {Promise<ResolvedChatAttachmentContent>} The resolved content.
+ * @private function of resolveChatAttachmentContents
+ */
+export declare function resolveChatAttachmentContent(attachment: ChatAttachment, maxInlineCharacters: number, options?: ResolveChatAttachmentOptions): Promise<ResolvedChatAttachmentContent>;

package/umd/src/utils/chat/chatAttachments/resolveChatAttachmentContents.d.ts

@@ -0,0 +1,10 @@
+import type { ChatAttachment, ResolveChatAttachmentOptions, ResolvedChatAttachmentContent } from '../chatAttachments';
+/**
+ * Resolves inline content previews for each attachment while enforcing global prompt-size limits.
+ *
+ * @param {ReadonlyArray<ChatAttachment>} attachments - The attachments to resolve.
+ * @param {ResolveChatAttachmentOptions} options - Options for resolution.
+ * @returns {Promise<Array<ResolvedChatAttachmentContent>>} The resolved contents.
+ * @public exported from `@promptbook/core`
+ */
+export declare function resolveChatAttachmentContents(attachments: ReadonlyArray<ChatAttachment>, options?: ResolveChatAttachmentOptions): Promise<Array<ResolvedChatAttachmentContent>>;

package/umd/src/utils/chat/chatAttachments.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Attachment payload expected by chat routes and prompt formatting helpers.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type ChatAttachment = {
+    readonly name: string;
+    readonly type: string;
+    readonly url: string;
+};
+/**
+ * Resolved inline content of one chat attachment.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type ResolvedChatAttachmentContent = {
+    readonly attachment: ChatAttachment;
+    readonly content: string | null;
+    readonly isTruncated: boolean;
+    readonly reason: string | null;
+    readonly encodingUsed: string | null;
+    readonly encodingConfidence: number | null;
+    readonly warnings: ReadonlyArray<string>;
+    readonly wasBinary: boolean;
+};
+/**
+ * Options for resolving chat attachment contents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type ResolveChatAttachmentOptions = {
+    /**
+     * Whether to allow localhost URLs.
+     *
+     * @default false
+     */
+    readonly allowLocalhost?: boolean;
+    /**
+     * Forces text decoding even when the attachment looks binary.
+     *
+     * @default false
+     */
+    readonly forceText?: boolean;
+};
+export { normalizeChatAttachments } from './chatAttachments/normalizeChatAttachments';
+export { formatChatAttachmentContext } from './chatAttachments/formatChatAttachmentContext';
+export { resolveChatAttachmentContent } from './chatAttachments/resolveChatAttachmentContent';
+export { resolveChatAttachmentContents } from './chatAttachments/resolveChatAttachmentContents';
+export { formatChatAttachmentContentContext } from './chatAttachments/formatChatAttachmentContentContext';
+export { appendChatAttachmentContext } from './chatAttachments/appendChatAttachmentContext';
+export { appendChatAttachmentContextWithContent } from './chatAttachments/appendChatAttachmentContextWithContent';
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/utils/chat/chatAttachments.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/utils/chat/constants.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @@@
+ *
+ * @private internal mechanism for chat stream whitespace encoding/decoding
+ */
+export declare const CHAT_STREAM_WHITESPACE_ENCODERS: ReadonlyArray<{
+    pattern: RegExp;
+    token: string;
+}>;
+/**
+ * @@@
+ *
+ * @private internal mechanism for chat stream whitespace encoding/decoding
+ */
+export declare const CHAT_STREAM_WHITESPACE_DECODERS: ReadonlyArray<{
+    token: string;
+    value: string;
+}>;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/utils/chat/decodeChatStreamWhitespaceFromTransport.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Converts encoded whitespace markers back into real whitespace so the UI can render the message
+ * exactly as it was generated.
+ *
+ * @private internal mechanism for chat stream whitespace encoding/decoding
+ */
+export declare function decodeChatStreamWhitespaceFromTransport(content: string): string;

package/umd/src/utils/chat/encodeChatStreamWhitespaceForTransport.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Replaces whitespace characters inside a streamed chunk with special markers so the transport
+ * never emits content that would otherwise be treated as empty.
+ *
+ * @private internal mechanism for chat stream whitespace encoding/decoding
+ */
+export declare function encodeChatStreamWhitespaceForTransport(content: string): string;

package/umd/src/utils/chat/escapeRegExp.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @@@
+ *
+ * @public exported from `@promptbook/utils`
+ */
+export declare function escapeRegExp(value: string): string;

package/umd/src/utils/database/uniqueConstraint.d.ts

@@ -0,0 +1,28 @@
+import type { PostgrestError } from '@supabase/postgrest-js';
+/**
+ * Holds the data necessary to translate a Postgres constraint name into a user-facing error.
+ *
+ * @private Internal helper for Supabase-backed collections
+ */
+export type UniqueConstraintTranslation = {
+    /**
+     * The suffix of the constraint name that should trigger this translation.
+     */
+    readonly suffix: string;
+    /**
+     * Builds the domain-specific error to throw when the constraint matches.
+     */
+    readonly buildError: () => Error;
+};
+/**
+ * Converts a Supabase unique constraint violation into a domain-specific error.
+ *
+ * @param error - Resulting Postgrest error from Supabase.
+ * @param translations - Array of translations keyed by constraint suffix.
+ * @returns A translated error when the constraint suffix matches, otherwise `null`.
+ * @private Internal helper for Supabase-backed collections
+ */
+export declare function translateSupabaseUniqueConstraintError(error: PostgrestError | null, translations: ReadonlyArray<UniqueConstraintTranslation>): Error | null;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/utils/files/decodeAttachmentAsText.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Input payload accepted by `decodeAttachmentAsText`.
+ *
+ * @private internal utility for shared text decoding
+ */
+export type DecodeAttachmentAsTextInput = {
+    /**
+     * Raw file bytes to inspect and decode.
+     */
+    readonly bytes: ArrayBuffer | ArrayBufferView;
+    /**
+     * Original filename used for diagnostics.
+     */
+    readonly filename: string;
+    /**
+     * Optional MIME type from transport or storage metadata.
+     */
+    readonly mimeType?: string | null;
+};
+/**
+ * Optional settings for `decodeAttachmentAsText`.
+ *
+ * @private internal utility for shared text decoding
+ */
+export type DecodeAttachmentAsTextOptions = {
+    /**
+     * Max bytes to decode before truncating the payload.
+     *
+     * @default 524288
+     */
+    readonly maxBytes?: number;
+    /**
+     * Forces text decoding even when the bytes look binary.
+     *
+     * @default false
+     */
+    readonly forceText?: boolean;
+};
+/**
+ * Best-effort text-decoding result for one attachment or file.
+ *
+ * @private internal utility for shared text decoding
+ */
+export type DecodeAttachmentAsTextResult = {
+    /**
+     * Decoded text. Empty string when decoding is skipped for binary content.
+     */
+    readonly text: string;
+    /**
+     * Encoding label used for decoding, or `binary` when decoding was skipped.
+     */
+    readonly encodingUsed: string;
+    /**
+     * Confidence score from `0` to `1`.
+     */
+    readonly confidence?: number;
+    /**
+     * Human-readable warnings describing truncation or guessed encodings.
+     */
+    readonly warnings: Array<string>;
+    /**
+     * Whether the payload was classified as binary and therefore not decoded.
+     */
+    readonly wasBinary: boolean;
+    /**
+     * Whether the byte payload had to be truncated before decoding.
+     */
+    readonly isTruncated: boolean;
+};
+/**
+ * Default byte limit for one best-effort text decode.
+ *
+ * @private constant of decodeAttachmentAsText
+ */
+export declare const DEFAULT_ATTACHMENT_TEXT_DECODE_BYTES: number;
+/**
+ * Best-effort decoder for uploaded or remote file bytes whose extension or encoding may be unknown.
+ *
+ * @private internal utility for shared text decoding
+ */
+export declare function decodeAttachmentAsText(input: DecodeAttachmentAsTextInput, options?: DecodeAttachmentAsTextOptions): DecodeAttachmentAsTextResult;

package/umd/src/utils/files/decodeAttachmentAsText.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/utils/files/readResponseBytes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reads a bounded byte prefix from a fetch `Response`.
+ *
+ * @param {Response} response - HTTP response whose body should be consumed.
+ * @param {number} maxBytes - Maximum number of bytes to capture.
+ * @param {{ captureOverflowByte?: boolean }} [options] - Optional capture behavior.
+ * @returns {Promise<{ bytes: Uint8Array }>} Captured bytes, optionally including one overflow byte.
+ * @private internal utility for bounded response reads
+ */
+export declare function readResponseBytes(response: Response, maxBytes: number, options?: {
+    captureOverflowByte?: boolean;
+}): Promise<{
+    readonly bytes: Uint8Array;
+}>;

package/umd/src/utils/random/EnglishNamePool.d.ts

@@ -1,4 +1,12 @@
-import type { NamePool } from './NamePool';
+import type { GenerateNameResult, NamePool } from './NamePool';
+/**
+ * Generates a deterministic English full name from an arbitrary seed text.
+ *
+ * @param seed - Input seed used to derive a stable pseudonym.
+ * @returns Deterministic English full name with color metadata.
+ * @private internal helper for deterministic pseudonym generation
+ */
+export declare function generateDeterministicEnglishName(seed: string): GenerateNameResult;
 /**
  * Name pool for English names
  *

package/umd/src/utils/toolCalls/getToolCallIdentity.d.ts

@@ -5,6 +5,6 @@ import type { ToolCall } from '../../types/ToolCall';
  * @param toolCall - Tool call entry to identify.
  * @returns Stable identity string for deduplication.
  *
- * @private function of <Chat/>
+ * @private function of `<Chat/>`
  */
 export declare function getToolCallIdentity(toolCall: ToolCall): string;

package/umd/src/utils/toolCalls/mergeToolCalls.d.ts

@@ -0,0 +1,12 @@
+import type { ToolCall } from '../../types/ToolCall';
+/**
+ * Merges streamed tool-call snapshots by stable identity while preserving incremental logs,
+ * warnings, and partial results.
+ *
+ * @param existingToolCalls - Previously known tool-call snapshots.
+ * @param incomingToolCalls - Newly observed tool-call snapshots.
+ * @returns Aggregated tool-call list with newer snapshots merged in place.
+ *
+ * @private shared helper for streaming chat surfaces
+ */
+export declare function mergeToolCalls(existingToolCalls: ReadonlyArray<ToolCall> | undefined, incomingToolCalls: ReadonlyArray<ToolCall> | undefined): Array<ToolCall>;

package/umd/src/utils/toolCalls/resolveToolCallIdempotencyKey.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCall } from '../../types/ToolCall';
+/**
+ * Builds a deterministic idempotency key for tool calls so the UI can track updates.
+ *
+ * @param toolCall - Tool call payload or snapshot.
+ * @returns Stable key that identifies the same tool call instance.
+ *
+ * @private internal helper for tool call streaming
+ */
+export declare function resolveToolCallIdempotencyKey(toolCall: ToolCall): string;

package/umd/src/utils/validators/url/extractUrlsFromText.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extracts all valid URLs from arbitrary text while removing common trailing punctuation.
+ *
+ * @param text - Input text that may contain one or more URLs.
+ * @returns Unique URLs in their first-seen order.
+ * @private utility of KNOWLEDGE parsing
+ */
+export declare function extractUrlsFromText(text: string): string[];

package/umd/src/utils/validators/url/extractUrlsFromText.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/utils/validators/url/isHostnameOnPrivateNetwork.d.ts

@@ -1,4 +1,15 @@
 import type { string_hostname } from '../../../types/typeAliases';
+/**
+ * Options for `isHostnameOnPrivateNetwork`
+ */
+export type IsHostnameOnPrivateNetworkOptions = {
+    /**
+     * Whether to allow localhost
+     *
+     * @default false
+     */
+    readonly allowLocalhost?: boolean;
+};
 /**
  * Checks if an URL is reserved for private networks or localhost.
  *
@@ -8,4 +19,4 @@ import type { string_hostname } from '../../../types/typeAliases';
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function isHostnameOnPrivateNetwork(hostname: string_hostname): boolean;
+export declare function isHostnameOnPrivateNetwork(hostname: string_hostname, options?: IsHostnameOnPrivateNetworkOptions): boolean;

package/umd/src/utils/validators/url/isUrlOnPrivateNetwork.d.ts

@@ -1,4 +1,9 @@
 import type { string_url } from '../../../types/typeAliases';
+import { type IsHostnameOnPrivateNetworkOptions } from './isHostnameOnPrivateNetwork';
+/**
+ * Options for `isUrlOnPrivateNetwork`
+ */
+export type IsUrlOnPrivateNetworkOptions = IsHostnameOnPrivateNetworkOptions;
 /**
  * Checks if an IP address or hostname is reserved for private networks or localhost.
  *
@@ -6,8 +11,9 @@ import type { string_url } from '../../../types/typeAliases';
  * - `isUrlOnPrivateNetwork` *(this one)* which tests full URL
  * - `isHostnameOnPrivateNetwork` which tests just hostname
  *
- * @param {string} ipAddress - The IP address to check.
+ * @param {string} url - The URL to check.
+ * @param {IsUrlOnPrivateNetworkOptions} options - Options for the check.
  * @returns {boolean} Returns true if the IP address is reserved for private networks or localhost, otherwise false.
  * @public exported from `@promptbook/utils`
  */
-export declare function isUrlOnPrivateNetwork(url: URL | string_url): boolean;
+export declare function isUrlOnPrivateNetwork(url: URL | string_url, options?: IsUrlOnPrivateNetworkOptions): boolean;

package/umd/src/utils/validators/url/normalizeDomainForMatching.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Normalizes a domain-like string into a comparable hostname form.
+ *
+ * The returned value is lowercased and stripped to hostname only
+ * (protocol, path, query, hash, and port are removed).
+ *
+ * @param rawDomain - Raw domain value (for example `my-agent.com` or `https://my-agent.com/path`).
+ * @returns Normalized hostname or `null` when the value cannot be normalized.
+ * @private utility for host/domain matching
+ */
+export declare function normalizeDomainForMatching(rawDomain: string): string | null;

package/umd/src/utils/validators/url/normalizeDomainForMatching.test.d.ts

@@ -0,0 +1 @@
+export {};

package/umd/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.111.0-6`).
+ * It follows semantic versioning (e.g., `0.112.0-0`).
  *
  * @generated
  */