memobirdsdk 1.0.0

package/dist/types/api.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Base response structure for all API calls
+ */
+export interface BaseResponse {
+    /** Return code, 1 for success, other values for failure */
+    showapi_res_code: number;
+    /** Error message when showapi_res_code !== 1 */
+    showapi_res_error: string;
+}
+/**
+ * Request parameters for binding a user to a device
+ */
+export interface BindUserRequest {
+    /** Access Key */
+    ak: string;
+    /** Timestamp in format 'YYYY-MM-DD HH:mm:ss' */
+    timestamp: string;
+    /** Memobird device ID (obtained by double-clicking the device) */
+    memobirdID: string;
+    /** User unique identifier */
+    useridentifying: string;
+}
+/**
+ * Response from binding a user to a device
+ */
+export interface BindUserResponse extends BaseResponse {
+    /** User ID returned after successful binding */
+    showapi_userid?: number;
+}
+/**
+ * Request parameters for printing content
+ */
+export interface PrintRequest {
+    /** Access Key */
+    ak: string;
+    /** Timestamp in format 'YYYY-MM-DD HH:mm:ss' */
+    timestamp: string;
+    /** Print content in format 'T:base64text' or 'P:base64image' */
+    printcontent: string;
+    /** Memobird device ID */
+    memobirdID: string;
+    /** User ID from binding response */
+    userID: number;
+}
+/**
+ * Response from print operations
+ */
+export interface PrintResponse extends BaseResponse {
+    /** 1 if printed, 0 or other values if not printed */
+    result?: number;
+    /** Unique ID for the print content */
+    printcontentid?: number;
+    /** Device GUID */
+    smartGuid?: string;
+}
+/**
+ * Request parameters for checking print status
+ */
+export interface PrintStatusRequest {
+    /** Access Key */
+    ak: string;
+    /** Timestamp in format 'YYYY-MM-DD HH:mm:ss' */
+    timestamp: string;
+    /** Print content ID from print response */
+    printcontentid: string;
+}
+/**
+ * Response from print status check
+ */
+export interface PrintStatusResponse extends BaseResponse {
+    /** 1 if printed, 0 or other values if not printed */
+    printflag?: number;
+    /** Print content ID */
+    printcontentID?: string;
+}
+/**
+ * Request parameters for converting image to monochrome bitmap
+ */
+export interface ConvertImageRequest {
+    /** Access Key */
+    ak: string;
+    /** JPG or PNG image as Base64 string */
+    imgBase64String: string;
+}
+/**
+ * Response from image conversion
+ */
+export interface ConvertImageResponse extends BaseResponse {
+    /** Monochrome bitmap Base64 string ready for printing */
+    result?: string;
+}
+/**
+ * Request parameters for printing from URL
+ */
+export interface PrintFromUrlRequest {
+    /** Access Key */
+    ak: string;
+    /** Timestamp in format 'YYYY-MM-DD HH:mm:ss' */
+    timestamp: string;
+    /** URL of the web page to print */
+    printUrl: string;
+    /** Memobird device ID */
+    memobirdID: string;
+    /** User ID from binding response */
+    userID: number;
+}
+/**
+ * Request parameters for printing from HTML
+ */
+export interface PrintFromHtmlRequest {
+    /** Access Key */
+    ak: string;
+    /** Timestamp in format 'YYYY-MM-DD HH:mm:ss' */
+    timestamp: string;
+    /** HTML source as GBK Base64 + URL encoded */
+    printHtml: string;
+    /** Memobird device ID */
+    memobirdID: string;
+    /** User ID from binding response */
+    userID: number;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/types/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/types/api.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IAEzB,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IAEnB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IAErB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,kBAAkB;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uBAAuB;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,iBAAiB;IACjB,EAAE,EAAE,MAAM,CAAC;IAEX,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAElB,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;IAEnB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/types/api.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=api.js.map

package/dist/types/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/types/api.ts"],"names":[],"mappings":""}

package/dist/types/common.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Content type for print operations
+ */
+export type ContentType = 'text' | 'image';
+/**
+ * Print status values
+ */
+export declare enum PrintStatus {
+    /** Print completed successfully */
+    PRINTED = 1,
+    /** Print pending or failed */
+    PENDING = 0
+}
+/**
+ * API success code
+ */
+export declare const API_SUCCESS_CODE = 1;
+/**
+ * Content item for mixed content printing
+ */
+export interface ContentItem {
+    /** Type of content */
+    type: ContentType;
+    /** Content string (text or base64 image) */
+    content: string;
+}
+//# sourceMappingURL=common.d.ts.map

package/dist/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3C;;GAEG;AACH,oBAAY,WAAW;IACrB,mCAAmC;IACnC,OAAO,IAAI;IACX,8BAA8B;IAC9B,OAAO,IAAI;CACZ;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types/common.js

@@ -0,0 +1,15 @@
+/**
+ * Print status values
+ */
+export var PrintStatus;
+(function (PrintStatus) {
+    /** Print completed successfully */
+    PrintStatus[PrintStatus["PRINTED"] = 1] = "PRINTED";
+    /** Print pending or failed */
+    PrintStatus[PrintStatus["PENDING"] = 0] = "PENDING";
+})(PrintStatus || (PrintStatus = {}));
+/**
+ * API success code
+ */
+export const API_SUCCESS_CODE = 1;
+//# sourceMappingURL=common.js.map

package/dist/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,MAAM,CAAN,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,mCAAmC;IACnC,mDAAW,CAAA;IACX,8BAA8B;IAC9B,mDAAW,CAAA;AACb,CAAC,EALW,WAAW,KAAX,WAAW,QAKtB;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC"}

package/dist/types/config.d.ts

@@ -0,0 +1,32 @@
+import type { Options } from 'got';
+/**
+ * Retry configuration for failed requests
+ */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Initial delay in milliseconds before first retry (default: 1000) */
+    initialDelay?: number;
+    /** Multiplier for exponential backoff (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum delay in milliseconds between retries (default: 10000) */
+    maxDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryStatusCodes?: number[];
+}
+/**
+ * Memobird SDK configuration
+ */
+export interface MemobirdConfig {
+    /** Access Key obtained from open.memobird.cn */
+    ak: string;
+    /** Base URL for API requests (default: 'http://open.memobird.cn/home') */
+    baseUrl?: string;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry configuration for failed requests */
+    retry?: RetryConfig;
+    /** Custom got HTTP client options */
+    httpOptions?: Partial<Options>;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,8FAA8F;IAC9F,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IAEX,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,qCAAqC;IACrC,WAAW,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CAChC"}

package/dist/types/config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.js.map

package/dist/types/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":""}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for Memobird SDK
+ * @module types
+ */
+export * from './api.js';
+export * from './common.js';
+export * from './config.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,8 @@
+/**
+ * Type definitions for Memobird SDK
+ * @module types
+ */
+export * from './api.js';
+export * from './common.js';
+export * from './config.js';
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/utils/content-formatter.d.ts

@@ -0,0 +1,49 @@
+import type { ContentItem } from '../types/index.js';
+/**
+ * Formats text content with T: prefix for printing
+ *
+ * Automatically converts UTF-8 text to GBK Base64 encoding as required by the API.
+ *
+ * @param text - Text content to print
+ * @returns Formatted print content (T:base64...)
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatTextContent('Hello World');
+ * // Returns: 'T:SGVsbG8gV29ybGQ='
+ * ```
+ */
+export declare function formatTextContent(text: string): string;
+/**
+ * Formats image content with P: prefix for printing
+ *
+ * @param base64Image - Monochrome bitmap Base64 image (should be pre-converted)
+ * @returns Formatted print content (P:base64...)
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatImageContent(monochromeBase64);
+ * // Returns: 'P:Qk0OAgAAAAAAAD4A...'
+ * ```
+ */
+export declare function formatImageContent(base64Image: string): string;
+/**
+ * Formats mixed content (text and images) for printing
+ *
+ * Combines multiple text and image items with pipe (|) separator.
+ *
+ * @param items - Array of content items with type and content
+ * @returns Formatted print content with T: and P: prefixes
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatMixedContent([
+ *   { type: 'text', content: 'Hello' },
+ *   { type: 'image', content: 'base64imagedata' },
+ *   { type: 'text', content: 'World' }
+ * ]);
+ * // Returns: 'T:SGVsbG8=|P:base64imagedata|T:V29ybGQ='
+ * ```
+ */
+export declare function formatMixedContent(items: ContentItem[]): string;
+//# sourceMappingURL=content-formatter.d.ts.map

package/dist/utils/content-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/content-formatter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAU/D"}

package/dist/utils/content-formatter.js

@@ -0,0 +1,65 @@
+import { textToGBKBase64 } from './encoding.js';
+/**
+ * Formats text content with T: prefix for printing
+ *
+ * Automatically converts UTF-8 text to GBK Base64 encoding as required by the API.
+ *
+ * @param text - Text content to print
+ * @returns Formatted print content (T:base64...)
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatTextContent('Hello World');
+ * // Returns: 'T:SGVsbG8gV29ybGQ='
+ * ```
+ */
+export function formatTextContent(text) {
+    const gbkBase64 = textToGBKBase64(text);
+    return `T:${gbkBase64}`;
+}
+/**
+ * Formats image content with P: prefix for printing
+ *
+ * @param base64Image - Monochrome bitmap Base64 image (should be pre-converted)
+ * @returns Formatted print content (P:base64...)
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatImageContent(monochromeBase64);
+ * // Returns: 'P:Qk0OAgAAAAAAAD4A...'
+ * ```
+ */
+export function formatImageContent(base64Image) {
+    return `P:${base64Image}`;
+}
+/**
+ * Formats mixed content (text and images) for printing
+ *
+ * Combines multiple text and image items with pipe (|) separator.
+ *
+ * @param items - Array of content items with type and content
+ * @returns Formatted print content with T: and P: prefixes
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatMixedContent([
+ *   { type: 'text', content: 'Hello' },
+ *   { type: 'image', content: 'base64imagedata' },
+ *   { type: 'text', content: 'World' }
+ * ]);
+ * // Returns: 'T:SGVsbG8=|P:base64imagedata|T:V29ybGQ='
+ * ```
+ */
+export function formatMixedContent(items) {
+    return items
+        .map((item) => {
+        if (item.type === 'text') {
+            return formatTextContent(item.content);
+        }
+        else {
+            return formatImageContent(item.content);
+        }
+    })
+        .join('|');
+}
+//# sourceMappingURL=content-formatter.js.map

package/dist/utils/content-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-formatter.js","sourceRoot":"","sources":["../../src/utils/content-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACxC,OAAO,KAAK,SAAS,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,OAAO,KAAK,WAAW,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAoB;IACrD,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YACzB,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,OAAO,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/utils/encoding.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Converts UTF-8 text to GBK encoded Base64 string
+ *
+ * This is required for Chinese characters in print content according to Memobird API documentation.
+ * The API expects Chinese text to be GBK encoded before Base64 conversion.
+ *
+ * @param text - UTF-8 text to convert
+ * @returns GBK Base64 encoded string
+ * @throws {ValidationError} If encoding fails
+ *
+ * @example
+ * ```typescript
+ * const encoded = textToGBKBase64('你好世界');
+ * console.log(encoded); // Outputs GBK Base64 string
+ * ```
+ */
+export declare function textToGBKBase64(text: string): string;
+/**
+ * Decodes GBK Base64 string back to UTF-8 text
+ *
+ * @param gbkBase64 - GBK Base64 encoded string
+ * @returns UTF-8 decoded text
+ * @throws {ValidationError} If decoding fails
+ *
+ * @example
+ * ```typescript
+ * const decoded = gbkBase64ToText(encodedString);
+ * console.log(decoded); // Outputs: '你好世界'
+ * ```
+ */
+export declare function gbkBase64ToText(gbkBase64: string): string;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/utils/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAUzD"}

package/dist/utils/encoding.js

@@ -0,0 +1,50 @@
+import iconv from 'iconv-lite';
+import { ValidationError } from '../errors/index.js';
+/**
+ * Converts UTF-8 text to GBK encoded Base64 string
+ *
+ * This is required for Chinese characters in print content according to Memobird API documentation.
+ * The API expects Chinese text to be GBK encoded before Base64 conversion.
+ *
+ * @param text - UTF-8 text to convert
+ * @returns GBK Base64 encoded string
+ * @throws {ValidationError} If encoding fails
+ *
+ * @example
+ * ```typescript
+ * const encoded = textToGBKBase64('你好世界');
+ * console.log(encoded); // Outputs GBK Base64 string
+ * ```
+ */
+export function textToGBKBase64(text) {
+    try {
+        const gbkBuffer = iconv.encode(text, 'gbk');
+        return gbkBuffer.toString('base64');
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to encode text to GBK Base64: ${error instanceof Error ? error.message : String(error)}`, 'text');
+    }
+}
+/**
+ * Decodes GBK Base64 string back to UTF-8 text
+ *
+ * @param gbkBase64 - GBK Base64 encoded string
+ * @returns UTF-8 decoded text
+ * @throws {ValidationError} If decoding fails
+ *
+ * @example
+ * ```typescript
+ * const decoded = gbkBase64ToText(encodedString);
+ * console.log(decoded); // Outputs: '你好世界'
+ * ```
+ */
+export function gbkBase64ToText(gbkBase64) {
+    try {
+        const buffer = Buffer.from(gbkBase64, 'base64');
+        return iconv.decode(buffer, 'gbk');
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to decode GBK Base64 to text: ${error instanceof Error ? error.message : String(error)}`, 'gbkBase64');
+    }
+}
+//# sourceMappingURL=encoding.js.map

package/dist/utils/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,OAAO,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAChG,MAAM,CACP,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAChD,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,wCAAwC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAChG,WAAW,CACZ,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/utils/image.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Validates if a string is a valid Base64 encoded string
+ *
+ * @param base64String - String to validate
+ * @returns true if valid Base64
+ *
+ * @example
+ * ```typescript
+ * isValidBase64Image('SGVsbG8gV29ybGQ='); // true
+ * isValidBase64Image('not-base64!@#'); // false
+ * ```
+ */
+export declare function isValidBase64Image(base64String: string): boolean;
+/**
+ * Strips Base64 data URL prefix if present
+ *
+ * Removes 'data:image/...;base64,' prefix from data URLs.
+ *
+ * @param base64String - Base64 string (may include data URL prefix)
+ * @returns Clean Base64 string without prefix
+ *
+ * @example
+ * ```typescript
+ * stripDataUrlPrefix('data:image/png;base64,iVBORw0KG...');
+ * // Returns: 'iVBORw0KG...'
+ * ```
+ */
+export declare function stripDataUrlPrefix(base64String: string): string;
+/**
+ * Reads an image file and converts it to Base64
+ *
+ * @param filePath - Path to image file
+ * @returns Promise resolving to Base64 encoded image
+ * @throws {ValidationError} If file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const base64 = await imageFileToBase64('./image.jpg');
+ * ```
+ */
+export declare function imageFileToBase64(filePath: string): Promise<string>;
+//# sourceMappingURL=image.d.ts.map

package/dist/utils/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/utils/image.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAGhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUzE"}

package/dist/utils/image.js

@@ -0,0 +1,58 @@
+import { promises as fs } from 'node:fs';
+import { ValidationError } from '../errors/index.js';
+/**
+ * Validates if a string is a valid Base64 encoded string
+ *
+ * @param base64String - String to validate
+ * @returns true if valid Base64
+ *
+ * @example
+ * ```typescript
+ * isValidBase64Image('SGVsbG8gV29ybGQ='); // true
+ * isValidBase64Image('not-base64!@#'); // false
+ * ```
+ */
+export function isValidBase64Image(base64String) {
+    const base64Pattern = /^[A-Za-z0-9+/]+=*$/;
+    return base64Pattern.test(base64String) && base64String.length % 4 === 0;
+}
+/**
+ * Strips Base64 data URL prefix if present
+ *
+ * Removes 'data:image/...;base64,' prefix from data URLs.
+ *
+ * @param base64String - Base64 string (may include data URL prefix)
+ * @returns Clean Base64 string without prefix
+ *
+ * @example
+ * ```typescript
+ * stripDataUrlPrefix('data:image/png;base64,iVBORw0KG...');
+ * // Returns: 'iVBORw0KG...'
+ * ```
+ */
+export function stripDataUrlPrefix(base64String) {
+    const dataUrlPattern = /^data:image\/[a-z]+;base64,/i;
+    return base64String.replace(dataUrlPattern, '');
+}
+/**
+ * Reads an image file and converts it to Base64
+ *
+ * @param filePath - Path to image file
+ * @returns Promise resolving to Base64 encoded image
+ * @throws {ValidationError} If file cannot be read
+ *
+ * @example
+ * ```typescript
+ * const base64 = await imageFileToBase64('./image.jpg');
+ * ```
+ */
+export async function imageFileToBase64(filePath) {
+    try {
+        const buffer = await fs.readFile(filePath);
+        return buffer.toString('base64');
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to read image file: ${error instanceof Error ? error.message : String(error)}`, 'filePath');
+    }
+}
+//# sourceMappingURL=image.js.map

package/dist/utils/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,aAAa,GAAG,oBAAoB,CAAC;IAC3C,OAAO,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,MAAM,cAAc,GAAG,8BAA8B,CAAC;IACtD,OAAO,YAAY,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IACtD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC3C,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CACvB,8BAA8B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EACtF,UAAU,CACX,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for Memobird SDK
+ * @module utils
+ */
+export * from './encoding.js';
+export * from './timestamp.js';
+export * from './content-formatter.js';
+export * from './image.js';
+export * from './retry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,10 @@
+/**
+ * Utility functions for Memobird SDK
+ * @module utils
+ */
+export * from './encoding.js';
+export * from './timestamp.js';
+export * from './content-formatter.js';
+export * from './image.js';
+export * from './retry.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}