@thunkier/thunkmetrc-wrapper 0.2.2 → 0.3.3

package/README.md

@@ -0,0 +1,67 @@
+# ThunkMetrc TypeScript Wrapper
+
+Type-safe, rate-limited, async wrapper for the Metrc API.
+
+## 📦 Installation
+
+```bash
+npm install @thunkier/thunkmetrc-wrapper
+npm install @thunkier/thunkmetrc-client
+```
+
+## 🚀 Getting Started
+
+### 1. Initialize
+Use `MetrcFactory` to handle shared rate limiting effectively.
+
+```typescript
+import { MetrcFactory } from '@thunkier/thunkmetrc-wrapper';
+
+// 1. Create Factory
+// Shared RateLimiter (150 requests/sec integrator limit)
+const factory = new MetrcFactory(150);
+
+// 2. Create Wrapper for specific license
+const metrc = factory.create(
+    "https://sandbox-api-or.metrc.com",
+    "vendor_key",
+    "user_key"
+);
+```
+
+### 2. Make Requests
+All service methods are `async`.
+
+```typescript
+try {
+    const facilities = await metrc.facilities.getFacilities();
+    facilities.forEach(f => {
+        console.log(`Facility: ${f.License.Number}`);
+    });
+} catch (e) {
+    console.error(e);
+}
+```
+
+### 3. Pagination (Async Iterator)
+Use the `iterate...` methods to stream pages comfortably.
+
+```typescript
+const iterator = metrc.packages.iterateGetActivePackages(
+    "123-ABC-LICENSE"
+);
+
+// Use for-await-of loop
+for await (const pkg of iterator) {
+    console.log(`Package: ${pkg.Label}`);
+}
+```
+
+## 🛡️ Rate Limiting
+The SDK uses `MetrcRateLimiter` to enforce:
+- **Integrator Limits**: Default 150/sec.
+- **Facility Limits**: Default 50/sec per facility.
+- **Backoff**: Exponential backoff on 429/500 errors.
+- **Retries**: Automatic retry logic.
+
+Configuration is handled via `MetrcFactory`.

package/dist/Factory.d.ts

@@ -0,0 +1,13 @@
+import { type Logger } from '@thunkier/thunkmetrc-client';
+import { MetrcWrapper } from './index';
+export interface MetrcFactoryConfig {
+    maxConcurrentRequests?: number;
+    logger?: Logger;
+    timeout?: number;
+}
+export declare class MetrcFactory {
+    private config;
+    private sharedLimiter;
+    constructor(config?: MetrcFactoryConfig);
+    create(baseUrl: string, vendorKey: string, userKey: string): MetrcWrapper;
+}

package/dist/Factory.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetrcFactory = void 0;
+const thunkmetrc_client_1 = require("@thunkier/thunkmetrc-client");
+const index_1 = require("./index");
+const RateLimiter_1 = require("./RateLimiter");
+class MetrcFactory {
+    constructor(config = {}) {
+        this.config = config;
+        const limConfig = new RateLimiter_1.RateLimiterConfig();
+        if (config.maxConcurrentRequests) {
+            limConfig.maxConcurrentGetIntegrator = config.maxConcurrentRequests;
+        }
+        this.sharedLimiter = new RateLimiter_1.MetrcRateLimiter(limConfig);
+    }
+    create(baseUrl, vendorKey, userKey) {
+        const client = new thunkmetrc_client_1.MetrcClient({
+            baseUrl,
+            vendorKey,
+            userKey,
+            timeout: this.config.timeout,
+            logger: this.config.logger
+        });
+        return new index_1.MetrcWrapper(client, this.sharedLimiter);
+    }
+}
+exports.MetrcFactory = MetrcFactory;

package/dist/RateLimiter.js

@@ -96,28 +96,51 @@ class MetrcRateLimiter {
         if (facility) {
             await this.getFacilityRate(facility).wait();
         }
-        // Retry loop
-        while (true) {
+        const maxRetries = 10;
+        const initialBackoffMs = 1000;
+        const maxBackoffMs = 60000;
+        const backoffExponent = 2;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 return await op();
             }
             catch (err) {
-                // Check for 429
-                if (err?.response?.status === 429 || (err?.message && err.message.includes('429'))) {
-                    // Backoff
+                // Check for 429 or 5xx
+                const status = err?.response?.status;
+                const is429 = status === 429 || (err?.message && err.message.includes('429'));
+                const is5xx = status >= 500 && status < 600;
+                if (!is429 && !is5xx) {
+                    throw err;
+                }
+                if (attempt === maxRetries) {
+                    throw err;
+                }
+                let waitMs = 0;
+                if (is429) {
+                    // Respect Retry-After
                     const retryAfterInfo = err?.response?.headers?.['retry-after'];
-                    let waitMs = 1000;
                     if (retryAfterInfo) {
                         const seconds = parseInt(retryAfterInfo, 10);
-                        if (!isNaN(seconds))
+                        if (!isNaN(seconds)) {
                             waitMs = seconds * 1000;
+                        }
                     }
-                    await new Promise(resolve => setTimeout(resolve, waitMs));
-                    continue;
                 }
-                throw err;
+                // If no Retry-After or 5xx, use Jittered Exponential Backoff
+                if (waitMs === 0) {
+                    const exponential = initialBackoffMs * Math.pow(backoffExponent, attempt);
+                    const capped = Math.min(exponential, maxBackoffMs);
+                    // Full Jitter: random between 0 and capped
+                    // Or Proportional Jitter: capped + random(0-20%)?
+                    // "Decorrelated Jitter" is often best, but Simple Full Jitter is standard.
+                    // Let's use Proportional Jitter to match C# logic (base + 0-20% jitter)
+                    const jitter = Math.random() * 0.2 * capped;
+                    waitMs = capped + jitter;
+                }
+                await new Promise(resolve => setTimeout(resolve, waitMs));
             }
         }
+        throw new Error("Max retries exceeded");
     }
     getFacilityRate(facility) {
         let tb = this.facilityRates.get(facility);

package/dist/Utils.d.ts

@@ -0,0 +1,3 @@
+import { PaginatedResponse } from './models';
+export declare function iteratePages<T>(fetchPage: (page: number) => Promise<PaginatedResponse<T> | T[] | null>): AsyncGenerator<T, void, unknown>;
+export declare function parallelSync<T>(targets: any[], concurrencyLimit: number, operation: (target: any) => Promise<T[]>): Promise<Record<string, T[]>>;

package/dist/Utils.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iteratePages = iteratePages;
+exports.parallelSync = parallelSync;
+async function* iteratePages(fetchPage) {
+    let page = 1;
+    while (true) {
+        const response = await fetchPage(page);
+        if (!response) {
+            break;
+        }
+        let items = [];
+        let totalPages;
+        if (Array.isArray(response)) {
+            items = response;
+            totalPages = 1;
+        }
+        else {
+            // Check if it has Data property (PaginatedResponse)
+            const paginated = response; // Cast to access optional props safely
+            if (paginated.Data && Array.isArray(paginated.Data)) {
+                items = paginated.Data;
+                totalPages = paginated.TotalPages;
+            }
+            else if (Array.isArray(paginated)) {
+                // Fallback if type overlap issues
+                items = paginated;
+            }
+        }
+        if (items.length === 0) {
+            break;
+        }
+        for (const item of items) {
+            yield item;
+        }
+        if (typeof totalPages === 'number' && page >= totalPages) {
+            break;
+        }
+        // Safety break if we assume 1 page for raw arrays
+        if (totalPages === 1) {
+            break;
+        }
+        page++;
+    }
+}
+async function parallelSync(targets, concurrencyLimit, operation) {
+    const results = {};
+    const queue = [...targets];
+    // Simple semaphore-like worker pool
+    const workers = Array(Math.min(concurrencyLimit, targets.length)).fill(null).map(async () => {
+        while (queue.length > 0) {
+            const target = queue.shift();
+            if (!target)
+                break;
+            try {
+                const items = await operation(target);
+                const lic = target.licenseNumber || target.license || String(target);
+                results[lic] = items;
+            }
+            catch (e) {
+                console.error(`Error processing target ${target}:`, e);
+            }
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}