memobirdsdk 1.0.0

package/dist/utils/retry.d.ts

@@ -0,0 +1,70 @@
+import type { RetryConfig } from '../types/index.js';
+/**
+ * Retry strategy with exponential backoff
+ *
+ * Automatically retries failed operations with increasing delays between attempts.
+ */
+export declare class RetryStrategy {
+    private config;
+    /**
+     * Creates a new RetryStrategy
+     *
+     * @param config - Retry configuration options
+     *
+     * @example
+     * ```typescript
+     * const strategy = new RetryStrategy({
+     *   maxRetries: 3,
+     *   initialDelay: 1000,
+     *   backoffMultiplier: 2
+     * });
+     * ```
+     */
+    constructor(config?: RetryConfig);
+    /**
+     * Executes a function with retry logic
+     *
+     * @param fn - Async function to execute
+     * @returns Promise with function result
+     * @throws Error from the function if all retries are exhausted
+     *
+     * @example
+     * ```typescript
+     * const result = await strategy.execute(async () => {
+     *   return await someApiCall();
+     * });
+     * ```
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Calculates delay for next retry attempt using exponential backoff
+     *
+     * @param attemptNumber - Current attempt number (0-indexed)
+     * @returns Delay in milliseconds
+     *
+     * @example
+     * ```typescript
+     * strategy.calculateDelay(0); // 1000ms
+     * strategy.calculateDelay(1); // 2000ms
+     * strategy.calculateDelay(2); // 4000ms
+     * ```
+     */
+    calculateDelay(attemptNumber: number): number;
+    /**
+     * Determines if error should trigger retry
+     *
+     * Retries on network errors and specific HTTP status codes (5xx, 408, 429).
+     * Does not retry on client errors (4xx except 408, 429).
+     *
+     * @param error - Error object
+     * @returns true if should retry
+     */
+    shouldRetry(error: unknown): boolean;
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    private sleep;
+}
+//# sourceMappingURL=retry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAcrD;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAwB;IAEtC;;;;;;;;;;;;;OAaG;gBACS,MAAM,GAAE,WAAgB;IAIpC;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA6BlD;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;IAM7C;;;;;;;;OAQG;IACH,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IA2BpC;;;;OAIG;IACH,OAAO,CAAC,KAAK;CAGd"}

package/dist/utils/retry.js

@@ -0,0 +1,132 @@
+import { NetworkError } from '../errors/index.js';
+/**
+ * Default retry configuration
+ */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 3,
+    initialDelay: 1000,
+    backoffMultiplier: 2,
+    maxDelay: 10000,
+    retryStatusCodes: [408, 429, 500, 502, 503, 504],
+};
+/**
+ * Retry strategy with exponential backoff
+ *
+ * Automatically retries failed operations with increasing delays between attempts.
+ */
+export class RetryStrategy {
+    config;
+    /**
+     * Creates a new RetryStrategy
+     *
+     * @param config - Retry configuration options
+     *
+     * @example
+     * ```typescript
+     * const strategy = new RetryStrategy({
+     *   maxRetries: 3,
+     *   initialDelay: 1000,
+     *   backoffMultiplier: 2
+     * });
+     * ```
+     */
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_RETRY_CONFIG, ...config };
+    }
+    /**
+     * Executes a function with retry logic
+     *
+     * @param fn - Async function to execute
+     * @returns Promise with function result
+     * @throws Error from the function if all retries are exhausted
+     *
+     * @example
+     * ```typescript
+     * const result = await strategy.execute(async () => {
+     *   return await someApiCall();
+     * });
+     * ```
+     */
+    async execute(fn) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry if this was the last attempt
+                if (attempt === this.config.maxRetries) {
+                    throw lastError;
+                }
+                // Don't retry if error shouldn't trigger retry
+                if (!this.shouldRetry(error)) {
+                    throw lastError;
+                }
+                // Calculate delay and wait before next attempt
+                const delay = this.calculateDelay(attempt);
+                await this.sleep(delay);
+            }
+        }
+        // This should never be reached, but TypeScript needs it
+        throw lastError || new Error('Unknown error during retry');
+    }
+    /**
+     * Calculates delay for next retry attempt using exponential backoff
+     *
+     * @param attemptNumber - Current attempt number (0-indexed)
+     * @returns Delay in milliseconds
+     *
+     * @example
+     * ```typescript
+     * strategy.calculateDelay(0); // 1000ms
+     * strategy.calculateDelay(1); // 2000ms
+     * strategy.calculateDelay(2); // 4000ms
+     * ```
+     */
+    calculateDelay(attemptNumber) {
+        const delay = this.config.initialDelay * Math.pow(this.config.backoffMultiplier, attemptNumber);
+        return Math.min(delay, this.config.maxDelay);
+    }
+    /**
+     * Determines if error should trigger retry
+     *
+     * Retries on network errors and specific HTTP status codes (5xx, 408, 429).
+     * Does not retry on client errors (4xx except 408, 429).
+     *
+     * @param error - Error object
+     * @returns true if should retry
+     */
+    shouldRetry(error) {
+        // Always retry NetworkError
+        if (error instanceof NetworkError) {
+            return true;
+        }
+        // Retry on specific HTTP status codes
+        if (typeof error === 'object' && error !== null && 'statusCode' in error) {
+            const statusCode = error.statusCode;
+            return this.config.retryStatusCodes.includes(statusCode);
+        }
+        // Retry on network-related errors (ECONNRESET, ETIMEDOUT, etc.)
+        if (error instanceof Error) {
+            const networkErrorCodes = [
+                'ECONNRESET',
+                'ECONNREFUSED',
+                'ETIMEDOUT',
+                'ENOTFOUND',
+                'ENETUNREACH',
+            ];
+            return networkErrorCodes.some((code) => error.message.includes(code));
+        }
+        return false;
+    }
+    /**
+     * Sleep for specified milliseconds
+     *
+     * @param ms - Milliseconds to sleep
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

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

package/dist/utils/timestamp.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Generates timestamp in Memobird API format (YYYY-MM-DD HH:mm:ss)
+ *
+ * @param date - Date object to format (defaults to current date/time)
+ * @returns Formatted timestamp string
+ *
+ * @example
+ * ```typescript
+ * const timestamp = generateTimestamp();
+ * console.log(timestamp); // '2025-12-29 14:30:45'
+ * ```
+ */
+export declare function generateTimestamp(date?: Date): string;
+/**
+ * Validates if a string matches Memobird timestamp format
+ *
+ * @param timestamp - Timestamp string to validate
+ * @returns true if valid format, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidTimestamp('2025-12-29 14:30:45'); // true
+ * isValidTimestamp('2025/12/29 14:30:45'); // false
+ * ```
+ */
+export declare function isValidTimestamp(timestamp: string): boolean;
+//# sourceMappingURL=timestamp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.d.ts","sourceRoot":"","sources":["../../src/utils/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,IAAiB,GAAG,MAAM,CASjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAG3D"}

package/dist/utils/timestamp.js

@@ -0,0 +1,38 @@
+/**
+ * Generates timestamp in Memobird API format (YYYY-MM-DD HH:mm:ss)
+ *
+ * @param date - Date object to format (defaults to current date/time)
+ * @returns Formatted timestamp string
+ *
+ * @example
+ * ```typescript
+ * const timestamp = generateTimestamp();
+ * console.log(timestamp); // '2025-12-29 14:30:45'
+ * ```
+ */
+export function generateTimestamp(date = new Date()) {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    const hours = String(date.getHours()).padStart(2, '0');
+    const minutes = String(date.getMinutes()).padStart(2, '0');
+    const seconds = String(date.getSeconds()).padStart(2, '0');
+    return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+/**
+ * Validates if a string matches Memobird timestamp format
+ *
+ * @param timestamp - Timestamp string to validate
+ * @returns true if valid format, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidTimestamp('2025-12-29 14:30:45'); // true
+ * isValidTimestamp('2025/12/29 14:30:45'); // false
+ * ```
+ */
+export function isValidTimestamp(timestamp) {
+    const pattern = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
+    return pattern.test(timestamp);
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/utils/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../src/utils/timestamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAa,IAAI,IAAI,EAAE;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAE3D,OAAO,GAAG,IAAI,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,IAAI,OAAO,IAAI,OAAO,EAAE,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,MAAM,OAAO,GAAG,uCAAuC,CAAC;IACxD,OAAO,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACjC,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "memobirdsdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for Memobird (咕咕机) thermal printer API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:examples": "tsc -p tsconfig.examples.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && npm run build:examples && node examples/test.js",
+    "example:basic": "npm run build && npm run build:examples && node examples/basic-usage.js",
+    "example:text": "npm run build && npm run build:examples && node examples/print-text.js",
+    "example:image": "npm run build && npm run build:examples && node examples/print-image.js",
+    "example:advanced": "npm run build && npm run build:examples && node examples/advanced.js"
+  },
+  "keywords": [
+    "memobird",
+    "thermal-printer",
+    "printer",
+    "sdk",
+    "gugumachine",
+    "iot",
+    "typescript",
+    "api-client"
+  ],
+  "author": "",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourusername/memobirdsdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/memobirdsdk/issues"
+  },
+  "homepage": "https://github.com/yourusername/memobirdsdk#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "dotenv": "^17.2.3",
+    "got": "^14.6.5",
+    "iconv-lite": "^0.6.3"
+  },
+  "devDependencies": {
+    "@types/dotenv": "^6.1.1",
+    "@types/node": "^20.19.27",
+    "typescript": "5.3"
+  }
+}