anz-legislation 1.2.1

package/dist/client.js

@@ -0,0 +1,492 @@
+/**
+ * API Client for NZ Legislation API
+ * Handles HTTP requests, authentication, rate limiting, and caching
+ */
+import got from 'got';
+import { LRUCache } from 'lru-cache';
+import { z } from 'zod';
+import { getConfig } from '@config';
+import { ConfigError, createApiError, ErrorCode, NetworkError } from '@errors';
+import { LegislationVersionSchema, SearchResultsSchema, VersionSchema, WorkSchema, WorkFromVersionSchema, } from '@models';
+import { logger } from '@utils/logger';
+/**
+ * Cache configuration
+ */
+const CACHE_CONFIG = {
+    // Max number of entries
+    max: 500,
+    // Default TTL: 1 hour
+    defaultTTL: 60 * 60 * 1000,
+    // TTL for search results: 30 minutes
+    searchTTL: 30 * 60 * 1000,
+    // TTL for work details: 2 hours
+    workTTL: 2 * 60 * 60 * 1000,
+    // TTL for versions: 1 hour
+    versionsTTL: 60 * 60 * 1000,
+};
+/**
+ * LRU Cache for API responses
+ */
+const cache = new LRUCache({
+    max: CACHE_CONFIG.max,
+    ttl: CACHE_CONFIG.defaultTTL,
+    updateAgeOnGet: false,
+    allowStale: false,
+});
+/**
+ * Rate limit state
+ */
+const rateLimitState = {
+    remaining: 10000,
+    resetTime: Date.now() + 86400000, // 24 hours from now
+    burstRemaining: 2000,
+    burstResetTime: Date.now() + 300000, // 5 minutes from now
+};
+const cacheMetrics = {
+    hits: 0,
+    misses: 0,
+    evictions: 0,
+    sets: 0,
+};
+/**
+ * Generate cache key from request parameters
+ */
+function generateCacheKey(endpoint, params) {
+    const paramString = params ? JSON.stringify(params) : '';
+    return `${endpoint}:${paramString}`;
+}
+/**
+ * Get data from cache
+ */
+function getFromCache(key) {
+    const entry = cache.get(key);
+    if (!entry) {
+        cacheMetrics.misses++;
+        logger.debug('Cache miss', { key });
+        return null;
+    }
+    const age = Date.now() - entry.timestamp;
+    if (age > entry.ttl) {
+        cache.delete(key);
+        cacheMetrics.evictions++;
+        cacheMetrics.misses++;
+        logger.debug('Cache expired', { key, age: `${age}ms` });
+        return null;
+    }
+    cacheMetrics.hits++;
+    logger.debug('Cache hit', { key, age: `${age}ms`, metrics: cacheMetrics });
+    return entry.data;
+}
+/**
+ * Set data in cache
+ */
+function setInCache(key, data, ttl) {
+    cache.set(key, {
+        data,
+        timestamp: Date.now(),
+        ttl,
+    });
+    cacheMetrics.sets++;
+    logger.debug('Cache set', { key, ttl: `${ttl}ms`, metrics: cacheMetrics });
+}
+/**
+ * Clear cache (optionally by pattern)
+ */
+export function clearCache(pattern) {
+    if (!pattern) {
+        cache.clear();
+        logger.info('Cache cleared');
+        return;
+    }
+    const keys = cache.keys();
+    for (const key of keys) {
+        if (key.includes(pattern)) {
+            cache.delete(key);
+        }
+    }
+    logger.info('Cache cleared', { pattern });
+}
+/**
+ * Get cache statistics
+ */
+export function getCacheStats() {
+    const total = cacheMetrics.hits + cacheMetrics.misses;
+    const hitRate = total > 0 ? ((cacheMetrics.hits / total) * 100).toFixed(2) : '0.00';
+    return {
+        size: cache.size,
+        maxSize: CACHE_CONFIG.max,
+        metrics: cacheMetrics,
+        hitRate: `${hitRate}%`,
+        keys: Array.from(cache.keys()).slice(0, 10), // First 10 keys
+    };
+}
+/**
+ * Reset cache metrics (for testing)
+ */
+export function resetCacheMetrics() {
+    cacheMetrics.hits = 0;
+    cacheMetrics.misses = 0;
+    cacheMetrics.evictions = 0;
+    cacheMetrics.sets = 0;
+}
+/**
+ * Check and enforce rate limits
+ */
+function checkRateLimit() {
+    const now = Date.now();
+    // Check daily limit
+    if (now >= rateLimitState.resetTime) {
+        rateLimitState.remaining = 10000;
+        rateLimitState.resetTime = now + 86400000;
+    }
+    // Check burst limit
+    if (now >= rateLimitState.burstResetTime) {
+        rateLimitState.burstRemaining = 2000;
+        rateLimitState.burstResetTime = now + 300000;
+    }
+    if (rateLimitState.remaining <= 0) {
+        const waitTime = Math.ceil((rateLimitState.resetTime - now) / 1000);
+        throw new Error(`Daily rate limit exceeded. Please wait ${waitTime} seconds or until midnight.`);
+    }
+    if (rateLimitState.burstRemaining <= 0) {
+        const waitTime = Math.ceil((rateLimitState.burstResetTime - now) / 1000);
+        throw new Error(`Burst rate limit exceeded. Please wait ${waitTime} seconds.`);
+    }
+}
+/**
+ * Type guard to check if value is a string array
+ */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+/**
+ * Helper to get a single header value (handles string[] and undefined)
+ * @param headers - Response headers object
+ * @param name - Header name to retrieve
+ * @returns Single header value or undefined
+ */
+function getHeaderValue(headers, name) {
+    const value = headers[name];
+    // Type guard: check if it's a string array
+    if (isStringArray(value)) {
+        return value[0];
+    }
+    // If it's a string or undefined, return as-is
+    return value;
+}
+/**
+ * Update rate limit state from response headers
+ */
+function updateRateLimitState(headers) {
+    const remaining = getHeaderValue(headers, 'x-ratelimit-remaining');
+    const reset = getHeaderValue(headers, 'x-ratelimit-reset');
+    const burstRemaining = getHeaderValue(headers, 'x-burst-remaining');
+    const burstReset = getHeaderValue(headers, 'x-burst-reset');
+    if (remaining) {
+        rateLimitState.remaining = parseInt(remaining, 10);
+    }
+    if (reset) {
+        rateLimitState.resetTime = parseInt(reset, 10) * 1000;
+    }
+    if (burstRemaining) {
+        rateLimitState.burstRemaining = parseInt(burstRemaining, 10);
+    }
+    if (burstReset) {
+        rateLimitState.burstResetTime = parseInt(burstReset, 10) * 1000;
+    }
+}
+/**
+ * Create HTTP client with proper configuration
+ */
+function createClient() {
+    const config = getConfig();
+    if (!config.apiKey) {
+        throw new ConfigError(ErrorCode.CONFIG_API_KEY_MISSING, 'API key is required. Set NZ_LEGISLATION_API_KEY or configure it with the CLI.');
+    }
+    return got.extend({
+        prefixUrl: config.baseUrl,
+        timeout: { request: config.timeout },
+        headers: {
+            Accept: 'application/json',
+            'User-Agent': 'nz-legislation-tool/1.0.0',
+        },
+        searchParams: {
+            api_key: config.apiKey,
+        },
+        retry: {
+            limit: 3,
+            methods: ['get'],
+            statusCodes: [408, 413, 429, 500, 502, 503, 504],
+            calculateDelay: ({ attemptCount, error }) => {
+                if (error.response?.statusCode === 429) {
+                    const retryAfter = getHeaderValue(error.response.headers, 'retry-after');
+                    if (retryAfter) {
+                        return parseInt(retryAfter, 10) * 1000;
+                    }
+                }
+                // Exponential backoff: 1s, 2s, 4s
+                return Math.pow(2, attemptCount - 1) * 1000;
+            },
+        },
+        hooks: {
+            afterResponse: [
+                (response) => {
+                    updateRateLimitState(response.headers);
+                    return response;
+                },
+            ],
+            beforeError: [
+                (error) => {
+                    // Add helpful context to errors
+                    if (error.response?.statusCode === 401) {
+                        error.message = 'Authentication failed. Please check your API key.';
+                    }
+                    else if (error.response?.statusCode === 404) {
+                        error.message = 'Resource not found. Please check the ID.';
+                    }
+                    else if (error.response?.statusCode === 429) {
+                        error.message = 'Rate limit exceeded. Please wait before making more requests.';
+                    }
+                    return error;
+                },
+            ],
+        },
+    });
+}
+let httpClientFactory = createClient;
+export function setHttpClientFactoryForTesting(factory) {
+    httpClientFactory = factory ?? createClient;
+}
+async function getWorkFromVersions(client, workId, cacheKey) {
+    const versionsData = (await client.get(`v0/works/${workId}/versions`).json());
+    const rawResults = Array.isArray(versionsData) ? versionsData : versionsData.results || [];
+    const candidates = z.array(WorkFromVersionSchema).parse(rawResults);
+    if (candidates.length === 0) {
+        throw createApiError(404, `v0/works/${workId}/versions`, `Failed to get work: Work not found for ID "${workId}"`);
+    }
+    const result = candidates.slice().sort((a, b) => b.date.localeCompare(a.date))[0];
+    result.versionCount = candidates.length;
+    setInCache(cacheKey, result, CACHE_CONFIG.workTTL);
+    return result;
+}
+/**
+ * Search for legislation works
+ */
+export async function searchWorks(params) {
+    const cacheKey = generateCacheKey('search', params);
+    // Try cache first
+    const cached = getFromCache(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    logger.startTimer('searchWorks');
+    checkRateLimit();
+    const client = httpClientFactory();
+    try {
+        const data = await client
+            .get('v0/works', {
+            searchParams: {
+                ...(params.query && { search_term: params.query }),
+                ...(params.type && {
+                    legislation_type: params.type === 'regulation' ? 'secondary_legislation' : params.type,
+                }),
+                ...(params.status && { legislation_status: params.status.replace(/-/g, '_') }),
+                ...(params.from && { from: params.from }),
+                ...(params.to && { to: params.to }),
+                ...(params.limit && { per_page: params.limit.toString() }),
+                ...(params.offset && {
+                    page: (Math.floor((params.offset || 0) / (params.limit || 20)) + 1).toString(),
+                }),
+            },
+        })
+            .json();
+        const result = SearchResultsSchema.parse(data);
+        // Cache the result
+        setInCache(cacheKey, result, CACHE_CONFIG.searchTTL);
+        const duration = logger.endTimer('searchWorks');
+        logger.debug('Search completed', {
+            results: result.results.length,
+            total: result.total,
+            duration: `${duration}ms`,
+        });
+        return result;
+    }
+    catch (error) {
+        logger.error('Search failed', error instanceof Error ? error : undefined, { params });
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        if (error instanceof Error && 'response' in error) {
+            const apiError = error;
+            if (apiError.response) {
+                throw createApiError(apiError.response.statusCode || 500, apiError.response.url || 'unknown', `Search failed: ${error.message}`);
+            }
+        }
+        throw new Error(`Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Get a specific work by ID
+ */
+export async function getWork(workId) {
+    const cacheKey = generateCacheKey('work', { id: workId });
+    // Try cache first
+    const cached = getFromCache(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    logger.startTimer('getWork');
+    checkRateLimit();
+    const client = httpClientFactory();
+    const preferVersionsEndpoint = workId.includes('_');
+    try {
+        if (preferVersionsEndpoint) {
+            const result = await getWorkFromVersions(client, workId, cacheKey);
+            const duration = logger.endTimer('getWork');
+            logger.debug('Work reconstructed from versions', {
+                workId,
+                versionCount: result.versionCount,
+                duration: `${duration}ms`,
+            });
+            return result;
+        }
+        const data = await client.get(`v0/works/${workId}`).json();
+        const result = WorkSchema.parse(data);
+        // Cache the result
+        setInCache(cacheKey, result, CACHE_CONFIG.workTTL);
+        const duration = logger.endTimer('getWork');
+        logger.debug('Work retrieved', { workId, duration: `${duration}ms` });
+        return result;
+    }
+    catch (error) {
+        const apiError = error instanceof Error && 'response' in error
+            ? error
+            : undefined;
+        // The live v0 API currently exposes work details reliably via the versions
+        // collection, while the single-work endpoint returns 404 for valid work IDs.
+        if (apiError?.response?.statusCode === 404) {
+            try {
+                const result = await getWorkFromVersions(client, workId, cacheKey);
+                const duration = logger.endTimer('getWork');
+                logger.debug('Work reconstructed from versions', {
+                    workId,
+                    versionCount: result.versionCount,
+                    duration: `${duration}ms`,
+                });
+                return result;
+            }
+            catch (fallbackError) {
+                if (fallbackError instanceof Error && 'response' in fallbackError) {
+                    const fallbackApiError = fallbackError;
+                    if (fallbackApiError.response) {
+                        throw createApiError(fallbackApiError.response.statusCode || 500, fallbackApiError.response.url || 'unknown', `Failed to get work: ${fallbackError.message}`);
+                    }
+                }
+                if (fallbackError instanceof Error && 'code' in fallbackError) {
+                    throw fallbackError;
+                }
+                throw new Error(`Failed to get work: ${fallbackError instanceof Error ? fallbackError.message : 'Unknown error'}`);
+            }
+        }
+        logger.error('Failed to get work', error instanceof Error ? error : undefined, { workId });
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        if (apiError?.response) {
+            throw createApiError(apiError.response.statusCode || 500, apiError.response.url || 'unknown', `Failed to get work: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+        throw new Error(`Failed to get work: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Get all versions of a work
+ */
+export async function getWorkVersions(workId) {
+    const cacheKey = generateCacheKey('versions', { workId });
+    // Try cache first
+    const cached = getFromCache(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    logger.startTimer('getWorkVersions');
+    checkRateLimit();
+    const client = httpClientFactory();
+    try {
+        const data = (await client.get(`v0/works/${workId}/versions`).json());
+        const rawResults = Array.isArray(data) ? data : data.results || [];
+        const result = z.array(VersionSchema).parse(rawResults);
+        // Cache the result
+        setInCache(cacheKey, result, CACHE_CONFIG.versionsTTL);
+        const duration = logger.endTimer('getWorkVersions');
+        logger.debug('Versions retrieved', { workId, count: result.length, duration: `${duration}ms` });
+        return result;
+    }
+    catch (error) {
+        logger.error('Failed to get versions', error instanceof Error ? error : undefined, { workId });
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        if (error instanceof Error && 'response' in error) {
+            const apiError = error;
+            if (apiError.response) {
+                throw createApiError(apiError.response.statusCode || 500, apiError.response.url || 'unknown', `Failed to get versions: ${error.message}`);
+            }
+        }
+        throw new Error(`Failed to get versions: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Get a specific version of a work
+ */
+export async function getVersion(versionId) {
+    const cacheKey = generateCacheKey('version', { versionId });
+    // Try cache first
+    const cached = getFromCache(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    logger.startTimer('getVersion');
+    checkRateLimit();
+    const client = httpClientFactory();
+    try {
+        const data = await client.get(`v0/versions/${versionId}`).json();
+        const result = LegislationVersionSchema.parse(data);
+        // Cache the result
+        setInCache(cacheKey, result, CACHE_CONFIG.versionsTTL);
+        const duration = logger.endTimer('getVersion');
+        logger.debug('Version retrieved', { versionId, duration: `${duration}ms` });
+        return result;
+    }
+    catch (error) {
+        logger.error('Failed to get version', error instanceof Error ? error : undefined, {
+            versionId,
+        });
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        if (error instanceof Error && 'response' in error) {
+            const apiError = error;
+            if (apiError.response) {
+                throw createApiError(apiError.response.statusCode || 500, apiError.response.url || 'unknown', `Failed to get version: ${error.message}`);
+            }
+        }
+        throw new Error(`Failed to get version: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Get rate limit status
+ */
+export function getRateLimitStatus() {
+    return {
+        remaining: rateLimitState.remaining,
+        resetTime: new Date(rateLimitState.resetTime),
+        burstRemaining: rateLimitState.burstRemaining,
+        burstResetTime: new Date(rateLimitState.burstResetTime),
+    };
+}
+/**
+ * Get cache metrics
+ */
+export function getCacheMetrics() {
+    return { ...cacheMetrics };
+}

package/dist/commands/batch.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Batch Command - Execute bulk operations
+ */
+import { Command } from 'commander';
+export declare const batchCommand: Command;

package/dist/commands/batch.js

@@ -0,0 +1,121 @@
+/**
+ * Batch Command - Execute bulk operations
+ */
+import { readFileSync } from 'fs';
+import { Command } from 'commander';
+import ora from 'ora';
+import { BatchExecutor, createBatchFromFile, createBatchFromIds, formatBatchResults, saveBatchResults, } from '@utils/batch';
+export const batchCommand = new Command()
+    .name('batch')
+    .description('Execute bulk operations with batching')
+    .option('-f, --file <path>', 'Input file with IDs (CSV or JSON)')
+    .option('-i, --ids <ids>', 'Comma-separated list of IDs')
+    .requiredOption('-t, --type <type>', 'Operation type (search, getWork, getVersions, getVersion)')
+    .option('-o, --output <path>', 'Output file path')
+    .option('-F, --format <format>', 'Output format (json, csv)', 'json')
+    .option('-c, --concurrency <number>', 'Concurrent requests', '5')
+    .option('-r, --retry', 'Retry failed requests', false)
+    .option('--id-column <column>', 'Column name for ID in CSV (default: "id")')
+    .action(async (options) => {
+    if (!options.file && !options.ids) {
+        console.error('Error: Either --file or --ids is required');
+        process.exit(1);
+    }
+    const spinner = ora('Preparing batch...').start();
+    try {
+        let requests = [];
+        // Load requests from file or IDs
+        if (options.file) {
+            spinner.text = 'Loading input file...';
+            const content = readFileSync(options.file, 'utf-8');
+            if (options.file.endsWith('.json')) {
+                const data = JSON.parse(content);
+                if (Array.isArray(data)) {
+                    requests = createBatchFromFile(data, options.type, options.idColumn || 'id');
+                }
+                else {
+                    throw new Error('JSON file must contain an array of objects');
+                }
+            }
+            else if (options.file.endsWith('.csv')) {
+                // Simple CSV parsing (for production, use a proper CSV parser)
+                const lines = content.trim().split('\n');
+                const headers = lines[0].split(',');
+                const idColumnIndex = options.idColumn
+                    ? headers.indexOf(options.idColumn)
+                    : headers.indexOf('id');
+                if (idColumnIndex === -1) {
+                    throw new Error(`ID column "${options.idColumn || 'id'}" not found in CSV`);
+                }
+                const rows = lines.slice(1).map(line => {
+                    const values = line.split(',');
+                    return { [headers[idColumnIndex]]: values[idColumnIndex] };
+                });
+                requests = createBatchFromFile(rows, options.type, options.idColumn || 'id');
+            }
+            else {
+                throw new Error('Unsupported file format. Use CSV or JSON.');
+            }
+        }
+        else if (options.ids) {
+            const ids = options.ids
+                .split(',')
+                .map(id => id.trim())
+                .filter(id => id);
+            requests = createBatchFromIds(ids, options.type);
+        }
+        if (requests.length === 0) {
+            spinner.fail('No requests to process');
+            process.exit(1);
+        }
+        spinner.succeed(`Prepared ${requests.length} requests`);
+        // Create batch executor
+        const executor = new BatchExecutor({
+            concurrency: parseInt(options.concurrency, 10),
+            retryFailed: options.retry,
+            maxRetries: 3,
+        });
+        // Track progress
+        let lastProgress = 0;
+        executor.on('progress', (progress) => {
+            if (progress.percent - lastProgress >= 10) {
+                console.log(`  Progress: ${progress.percent}% (${progress.completed}/${progress.total})`);
+                lastProgress = progress.percent;
+            }
+        });
+        // Execute batch
+        console.log('\nExecuting batch operations...');
+        const results = await executor.execute(requests);
+        // Format results
+        const { successful, failed, cached, summary } = formatBatchResults(results);
+        // Print summary
+        console.log('\nBatch Execution Summary:');
+        console.log('─'.repeat(50));
+        console.log(`  Total:        ${summary.total}`);
+        console.log(`  Successful:   ${successful.length} (${summary.successRate}%)`);
+        console.log(`  Failed:       ${failed.length}`);
+        console.log(`  From Cache:   ${cached.length} (${summary.cacheHitRate}%)`);
+        console.log(`  Avg Duration: ${summary.averageDuration}ms`);
+        console.log(`  Total Time:   ${summary.totalDuration}ms`);
+        // Save results if output specified
+        if (options.output) {
+            saveBatchResults(results, options.output, options.format);
+            console.log(`\n✓ Results saved to: ${options.output}`);
+        }
+        // Exit with error if any failed
+        if (failed.length > 0) {
+            console.log(`\n⚠ ${failed.length} request(s) failed`);
+            if (failed.length <= 10) {
+                console.log('\nFailed requests:');
+                failed.forEach(r => {
+                    console.log(`  - ${r.id}: ${r.error?.message}`);
+                });
+            }
+        }
+    }
+    catch (error) {
+        spinner.fail('Batch operation failed');
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});

package/dist/commands/cache.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cache command - Manage API response cache
+ */
+import { Command } from 'commander';
+export declare const cacheCommand: Command;

package/dist/commands/cache.js

@@ -0,0 +1,43 @@
+/**
+ * Cache command - Manage API response cache
+ */
+import { Command } from 'commander';
+import { clearCache, getCacheStats } from '@client';
+import { logger } from '@utils/logger';
+export const cacheCommand = new Command()
+    .name('cache')
+    .description('Manage API response cache')
+    .option('--clear', 'Clear all cached data')
+    .option('--pattern <pattern>', 'Clear cache entries matching pattern')
+    .option('--stats', 'Show cache statistics')
+    .action((options) => {
+    try {
+        if (options.stats || (!options.clear && !options.pattern)) {
+            // Show stats by default
+            const stats = getCacheStats();
+            console.log('Cache Statistics:');
+            console.log(`  Size: ${stats.size} / ${stats.maxSize} entries`);
+            if (stats.keys.length > 0) {
+                console.log('  Recent keys:');
+                stats.keys.forEach((key, i) => {
+                    console.log(`    ${i + 1}. ${key}`);
+                });
+            }
+        }
+        if (options.clear) {
+            if (options.pattern) {
+                clearCache(options.pattern);
+                console.log(`Cache entries matching "${options.pattern}" cleared.`);
+            }
+            else {
+                clearCache();
+                console.log('Cache cleared.');
+            }
+        }
+    }
+    catch (error) {
+        logger.error('Cache operation failed', error instanceof Error ? error : undefined);
+        console.error('Error:', error instanceof Error ? error.message : 'Unknown error');
+        process.exit(1);
+    }
+});

package/dist/commands/cite.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Cite command - Generate citations
+ */
+import { Command } from 'commander';
+export declare const citeCommand: Command;