@agentick/shared 0.0.1

package/dist/blocks.js

@@ -0,0 +1,209 @@
+/**
+ * Content Blocks - Type-safe content block definitions using discriminated unions.
+ *
+ * Content blocks represent the atomic units of content in messages. They use
+ * discriminated unions (the `type` field) for type-safe handling:
+ *
+ * - **Text** - Plain text content (`TextBlock`)
+ * - **Media** - Images, audio, video, documents (`ImageBlock`, `AudioBlock`, etc.)
+ * - **Tool** - Tool calls and results (`ToolUseBlock`, `ToolResultBlock`)
+ * - **Data** - Structured data (JSON, XML, CSV, HTML, code)
+ * - **Events** - User actions, system events, state changes
+ *
+ * @example Type narrowing with discriminated unions
+ * ```typescript
+ * function processBlock(block: ContentBlock) {
+ *   switch (block.type) {
+ *     case 'text':
+ *       console.log(block.text); // TypeScript knows this is TextBlock
+ *       break;
+ *     case 'tool_use':
+ *       console.log(block.name, block.input); // ToolUseBlock
+ *       break;
+ *     case 'image':
+ *       console.log(block.source); // ImageBlock
+ *       break;
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link ContentBlock} - The union of all content block types
+ * @see {@link BlockType} - Enum of block type discriminators
+ *
+ * @module
+ */
+// ============================================================================
+// Helper Functions
+// ============================================================================
+export function isTextBlock(block) {
+    return block.type === "text";
+}
+export function isToolUseBlock(block) {
+    return block.type === "tool_use";
+}
+export function isToolResultBlock(block) {
+    return block.type === "tool_result";
+}
+export function isMediaBlock(block) {
+    return (block.type === "image" ||
+        block.type === "document" ||
+        block.type === "audio" ||
+        block.type === "video");
+}
+export function isEventBlock(block) {
+    return (block.type === "user_action" || block.type === "system_event" || block.type === "state_change");
+}
+export function isUserActionBlock(block) {
+    return block.type === "user_action";
+}
+export function isSystemEventBlock(block) {
+    return block.type === "system_event";
+}
+export function isStateChangeBlock(block) {
+    return block.type === "state_change";
+}
+export function extractText(blocks) {
+    return blocks
+        .filter(isTextBlock)
+        .map((b) => b.text)
+        .join("\n");
+}
+export function extractToolUses(blocks) {
+    return blocks.filter(isToolUseBlock);
+}
+// ============================================================================
+// Media Source Helpers
+// ============================================================================
+/**
+ * Browser-compatible base64 encoding helper.
+ * Uses Buffer in Node.js, browser APIs in browser.
+ * Uses globalThis to avoid requiring @types/node in browser environments.
+ */
+function uint8ArrayToBase64(bytes) {
+    // Node.js environment - use Buffer if available (via globalThis to avoid type dependency)
+    const BufferConstructor = globalThis.Buffer;
+    if (BufferConstructor && typeof BufferConstructor.from === "function") {
+        return BufferConstructor.from(bytes).toString("base64");
+    }
+    // Browser environment - use btoa with binary string conversion
+    let binary = "";
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Browser-compatible base64 decoding helper.
+ * Uses Buffer in Node.js, browser APIs in browser.
+ * Uses globalThis to avoid requiring @types/node in browser environments.
+ */
+function base64ToUint8Array(base64) {
+    // Node.js environment - use Buffer if available (via globalThis to avoid type dependency)
+    const BufferConstructor = globalThis.Buffer;
+    if (BufferConstructor && typeof BufferConstructor.from === "function") {
+        return new Uint8Array(BufferConstructor.from(base64, "base64"));
+    }
+    // Browser environment - use atob
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Convert a Buffer or Uint8Array to a serializable Base64Source.
+ *
+ * Browser-compatible: works in both Node.js and browser environments.
+ * Uses globalThis to avoid requiring @types/node in browser environments.
+ *
+ * @example
+ * ```typescript
+ * // Node.js
+ * const imageBuffer = await fs.readFile('image.png');
+ * const imageBlock: ImageBlock = {
+ *   type: 'image',
+ *   source: bufferToBase64Source(imageBuffer, 'image/png'),
+ * };
+ *
+ * // Browser
+ * const response = await fetch('image.png');
+ * const arrayBuffer = await response.arrayBuffer();
+ * const uint8Array = new Uint8Array(arrayBuffer);
+ * const imageBlock: ImageBlock = {
+ *   type: 'image',
+ *   source: bufferToBase64Source(uint8Array, 'image/png'),
+ * };
+ * ```
+ */
+export function bufferToBase64Source(buffer, mimeType) {
+    // Convert Buffer-like object to Uint8Array if needed (Node.js)
+    // Check via globalThis to avoid requiring @types/node
+    const BufferConstructor = globalThis.Buffer;
+    let bytes;
+    if (BufferConstructor &&
+        typeof BufferConstructor.isBuffer === "function" &&
+        BufferConstructor.isBuffer(buffer)) {
+        // It's a Node.js Buffer - extract underlying ArrayBuffer
+        bytes = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    }
+    else {
+        // It's already a Uint8Array
+        bytes = buffer;
+    }
+    const data = uint8ArrayToBase64(bytes);
+    return {
+        type: "base64",
+        data,
+        mimeType: mimeType,
+    };
+}
+/**
+ * Convert a Base64Source back to a Uint8Array.
+ *
+ * Browser-compatible: returns Uint8Array which works in both Node.js and browser.
+ * In Node.js, you can convert to Buffer if needed: `Buffer.from(uint8Array)`
+ *
+ * @example
+ * ```typescript
+ * if (imageBlock.source.type === 'base64') {
+ *   const uint8Array = base64SourceToBuffer(imageBlock.source);
+ *
+ *   // In Node.js, convert to Buffer if needed:
+ *   // const buffer = Buffer.from(uint8Array);
+ *
+ *   // In browser, use directly:
+ *   // const blob = new Blob([uint8Array], { type: 'image/png' });
+ * }
+ * ```
+ */
+export function base64SourceToBuffer(source) {
+    return base64ToUint8Array(source.data);
+}
+/**
+ * Check if a string looks like a URL (http:// or https://).
+ * Useful for determining source type from string data.
+ */
+export function isUrlString(str) {
+    return str.startsWith("http://") || str.startsWith("https://");
+}
+/**
+ * Create a MediaSource from a string (auto-detects URL vs base64).
+ *
+ * @example
+ * ```typescript
+ * const source = stringToMediaSource('https://example.com/image.png');
+ * // { type: 'url', url: 'https://example.com/image.png' }
+ *
+ * const source = stringToMediaSource('iVBORw0KGgo...');
+ * // { type: 'base64', data: 'iVBORw0KGgo...' }
+ * ```
+ */
+export function stringToMediaSource(str, mimeType) {
+    if (isUrlString(str)) {
+        return { type: "url", url: str, mimeType };
+    }
+    return { type: "base64", data: str, mimeType };
+}
+//# sourceMappingURL=blocks.js.map

package/dist/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}