anz-legislation 1.2.1

package/dist/providers/commonwealth-provider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Commonwealth (Federal) Australian Legislation Provider
+ *
+ * Provides access to Commonwealth legislation via the official Federal
+ * Register of Legislation API at https://api.prod.legislation.gov.au/v1/
+ */
+import { BaseLegislationProvider, type SearchParams, type SearchResults, type Work, type VersionSummary, type CitationStyle } from './legislation-provider.js';
+export declare class CommonwealthProvider extends BaseLegislationProvider {
+    private baseUrl;
+    constructor(_apiKey?: string);
+    /**
+     * Search Commonwealth legislation
+     */
+    protected searchImpl(params: SearchParams): Promise<SearchResults>;
+    /**
+     * Get specific Commonwealth work by ID
+     */
+    protected getWorkImpl(workId: string): Promise<Work>;
+    protected getVersionsImpl(_workId: string): Promise<VersionSummary[]>;
+    protected getVersionImpl(_versionId: string): Promise<Work>;
+    healthCheck(): Promise<void>;
+    /**
+     * Override citation generation for Australian style
+     */
+    getCitation(work: Work, style: CitationStyle): string;
+}
+export default CommonwealthProvider;

package/dist/providers/commonwealth-provider.js

@@ -0,0 +1,81 @@
+/**
+ * Commonwealth (Federal) Australian Legislation Provider
+ *
+ * Provides access to Commonwealth legislation via the official Federal
+ * Register of Legislation API at https://api.prod.legislation.gov.au/v1/
+ */
+import { logger } from '../utils/logger.js';
+import { BaseLegislationProvider, } from './legislation-provider.js';
+import { parseWorkIdMetadata } from './output-adapters.js';
+export class CommonwealthProvider extends BaseLegislationProvider {
+    baseUrl = 'https://api.prod.legislation.gov.au/v1';
+    constructor(_apiKey) {
+        // Default rate limit: 5 requests per second
+        super('au-comm', 'Australian Commonwealth', { requests: 5, per: 1 });
+    }
+    /**
+     * Search Commonwealth legislation
+     */
+    searchImpl(params) {
+        // The Federal Register of Legislation API /v1/search requires a specific OData filter
+        // implementation which is currently in development for the full scraper.
+        logger.debug('Searching Commonwealth legislation', { params });
+        return Promise.reject(new Error('Commonwealth search is currently in development. Please use direct ID retrieval with "nzlegislation get <id> --jurisdiction au-comm".'));
+    }
+    /**
+     * Get specific Commonwealth work by ID
+     */
+    getWorkImpl(workId) {
+        // Placeholder for direct ID retrieval
+        // In a real implementation, this would call /v1/Titles('{id}')
+        const metadata = parseWorkIdMetadata(workId);
+        return Promise.resolve({
+            ...metadata,
+            work_id: workId,
+            title: `${workId} (Cth)`,
+            type: 'act',
+            status: 'in-force',
+            date: new Date().toISOString().split('T')[0],
+            url: `https://www.legislation.gov.au/Details/${workId}`,
+            versionCount: 1,
+            jurisdiction: 'au-comm',
+            versions: [],
+            citations: {
+                nzmj: `${workId} (Cth)`,
+                australian: `${workId} (Cth)`,
+            },
+        });
+    }
+    getVersionsImpl(_workId) {
+        return Promise.resolve([]);
+    }
+    getVersionImpl(_versionId) {
+        return Promise.reject(new Error('Not implemented - scraper pending'));
+    }
+    async healthCheck() {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), 5000);
+        try {
+            const response = await fetch(`${this.baseUrl}/constitution`, {
+                method: 'HEAD',
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Health check failed with status ${response.status}`);
+            }
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Override citation generation for Australian style
+     */
+    getCitation(work, style) {
+        if (style === 'australian') {
+            return `${work.title} (Cth)`;
+        }
+        return super.getCitation(work, style);
+    }
+}
+export default CommonwealthProvider;

package/dist/providers/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Providers Index
+ *
+ * Central export point for all provider modules.
+ */
+export * from './legislation-provider.js';
+export * from './nz-provider.js';
+export * from './commonwealth-provider.js';
+export * from './queensland-provider.js';
+export * from './canonical-metadata.js';
+export * from './plugin-loader.js';
+export * from './plugin-discovery.js';
+export type { LegislationProvider, SearchParams, SearchResults, Work, WorkSummary, VersionSummary, CitationStyle, BaseLegislationProvider, ProviderRegistry, } from './legislation-provider.js';
+/**
+ * Initialize and register all first-party providers
+ */
+export declare function initializeProviders(config?: {
+    commonwealthApiKey?: string;
+    queenslandApiKey?: string;
+}): void;

package/dist/providers/index.js

@@ -0,0 +1,27 @@
+/**
+ * Providers Index
+ *
+ * Central export point for all provider modules.
+ */
+export * from './legislation-provider.js';
+export * from './nz-provider.js';
+export * from './commonwealth-provider.js';
+export * from './queensland-provider.js';
+export * from './canonical-metadata.js';
+export * from './plugin-loader.js';
+export * from './plugin-discovery.js';
+import { CommonwealthProvider } from './commonwealth-provider.js';
+import { getGlobalRegistry } from './legislation-provider.js';
+import { NZLegislationProvider } from './nz-provider.js';
+import { QueenslandProvider } from './queensland-provider.js';
+/**
+ * Initialize and register all first-party providers
+ */
+export function initializeProviders(config) {
+    const registry = getGlobalRegistry();
+    // Register NZ provider (default)
+    registry.register(new NZLegislationProvider());
+    // Register Australian providers
+    registry.register(new CommonwealthProvider(config?.commonwealthApiKey));
+    registry.register(new QueenslandProvider(config?.queenslandApiKey));
+}

package/dist/providers/legislation-provider.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Legislation Provider Interface
+ *
+ * Core interface that all jurisdiction providers must implement.
+ * Includes health monitoring, caching, and rate limiting support.
+ */
+import type { HealthCheckable, HealthStatus } from '../utils/health-monitor.js';
+import { RateLimiter } from '../utils/rate-limiter.js';
+import { ScraperCache } from '../utils/scraper-cache.js';
+/**
+ * Search parameters
+ */
+export interface SearchParams {
+    query?: string;
+    type?: 'act' | 'bill' | 'regulation' | 'instrument';
+    status?: 'in-force' | 'repealed' | 'not-in-force';
+    from?: string;
+    to?: string;
+    limit?: number;
+    offset?: number;
+}
+/**
+ * Search results
+ */
+export interface SearchResults {
+    total: number;
+    results: WorkSummary[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Work summary (lightweight)
+ */
+export interface WorkSummary {
+    work_id: string;
+    title: string;
+    type: string;
+    year: number;
+    number: number;
+    jurisdiction: string;
+    shortTitle?: string;
+    status?: string;
+    date?: string;
+    url?: string;
+    versionCount?: number;
+}
+/**
+ * Full work details
+ */
+export interface Work extends WorkSummary {
+    status: string;
+    versions: VersionSummary[];
+    citations: Record<string, string>;
+}
+/**
+ * Version summary
+ */
+export interface VersionSummary {
+    version_id: string;
+    title: string;
+    date: string;
+    is_current: boolean;
+    version?: number;
+    type?: string;
+    formats?: string[];
+}
+/**
+ * Citation styles
+ */
+export type CitationStyle = 'nzmj' | 'apa' | 'oscola' | 'australian' | 'bibtex' | 'ris' | 'enw';
+/**
+ * Legislation Provider Interface
+ *
+ * All jurisdiction providers (NZ, Australian states, etc.) must implement this.
+ */
+export interface LegislationProvider extends HealthCheckable {
+    /**
+     * Get jurisdiction identifier (e.g., 'nz', 'au-qld', 'au-comm')
+     */
+    getJurisdiction(): string;
+    /**
+     * Get jurisdiction display name (e.g., 'New Zealand', 'Queensland')
+     */
+    getDisplayName(): string;
+    /**
+     * Search legislation
+     */
+    search(params: SearchParams): Promise<SearchResults>;
+    /**
+     * Get work by ID
+     */
+    getWork(workId: string): Promise<Work>;
+    /**
+     * Get versions of a work
+     */
+    getVersions(workId: string): Promise<VersionSummary[]>;
+    /**
+     * Get specific version
+     */
+    getVersion(versionId: string): Promise<Work>;
+    /**
+     * Generate citation in specified style
+     */
+    getCitation(work: Work, style: CitationStyle): string;
+    /**
+     * Health check (from HealthCheckable)
+     */
+    healthCheck(): Promise<void>;
+}
+/**
+ * Base provider with common functionality
+ */
+export declare abstract class BaseLegislationProvider implements LegislationProvider {
+    protected cache: ScraperCache<unknown>;
+    protected rateLimiter: RateLimiter;
+    protected jurisdiction: string;
+    protected displayName: string;
+    constructor(jurisdiction: string, displayName: string, rateLimitOptions: {
+        requests: number;
+        per: number;
+    }, cacheOptions?: {
+        max?: number;
+        ttl?: number;
+    });
+    /**
+     * Get jurisdiction identifier
+     */
+    getJurisdiction(): string;
+    /**
+     * Get display name
+     */
+    getDisplayName(): string;
+    /**
+     * Search with caching and rate limiting
+     */
+    search(params: SearchParams): Promise<SearchResults>;
+    /**
+     * Get work with caching and rate limiting
+     */
+    getWork(workId: string): Promise<Work>;
+    /**
+     * Get versions with caching
+     */
+    getVersions(workId: string): Promise<VersionSummary[]>;
+    /**
+     * Get version with caching
+     */
+    getVersion(versionId: string): Promise<Work>;
+    /**
+     * Generate citation (default implementation)
+     */
+    getCitation(work: Work, style: CitationStyle): string;
+    /**
+     * Health check (from HealthCheckable)
+     */
+    healthCheck(): Promise<void>;
+    /**
+     * Get cache stats
+     */
+    getCacheStats(): ReturnType<ScraperCache<unknown>['getStats']>;
+    /**
+     * Get rate limit status
+     */
+    getRateLimitStatus(): ReturnType<RateLimiter['getStatus']>;
+    protected abstract searchImpl(params: SearchParams): Promise<SearchResults>;
+    protected abstract getWorkImpl(workId: string): Promise<Work>;
+    protected abstract getVersionsImpl(workId: string): Promise<VersionSummary[]>;
+    protected abstract getVersionImpl(versionId: string): Promise<Work>;
+    protected generateNzmjCitation(work: Work): string;
+    protected generateApaCitation(work: Work): string;
+    protected generateOscolaCitation(work: Work): string;
+    protected generateAustralianCitation(work: Work): string;
+    protected generateBibtexCitation(work: Work): string;
+    protected generateRisCitation(work: Work): string;
+    protected generateEnwCitation(work: Work): string;
+    protected getCitationYear(work: Work): string;
+    protected getCitationUrl(work: Work): string;
+}
+/**
+ * Provider registry
+ *
+ * Manages multiple legislation providers and provides
+ * health monitoring across all jurisdictions.
+ */
+export declare class ProviderRegistry {
+    private providers;
+    /**
+     * Register a provider
+     * @param provider - The legislation provider to register
+     */
+    register(provider: LegislationProvider): void;
+    /**
+     * Get provider by jurisdiction
+     * @param jurisdiction - The jurisdiction identifier
+     * @returns The provider or undefined if not found
+     */
+    get(jurisdiction: string): LegislationProvider | undefined;
+    /**
+     * Get all providers
+     * @returns Array of all registered providers
+     */
+    getAll(): LegislationProvider[];
+    /**
+     * Get all jurisdictions
+     * @returns Array of all jurisdiction identifiers
+     */
+    getJurisdictions(): string[];
+    /**
+     * Check if provider exists
+     * @param jurisdiction - The jurisdiction identifier
+     * @returns True if provider is registered
+     */
+    has(jurisdiction: string): boolean;
+    /**
+     * Get health dashboard for all providers
+     */
+    getHealthDashboard(): Promise<{
+        jurisdiction: string;
+        healthy: boolean;
+        status: HealthStatus;
+    }[]>;
+    /**
+     * Get health status for a provider
+     */
+    private getProviderHealth;
+}
+export declare function getGlobalRegistry(): ProviderRegistry;

package/dist/providers/legislation-provider.js

@@ -0,0 +1,308 @@
+/**
+ * Legislation Provider Interface
+ *
+ * Core interface that all jurisdiction providers must implement.
+ * Includes health monitoring, caching, and rate limiting support.
+ */
+import { RateLimiter } from '../utils/rate-limiter.js';
+import { ScraperCache } from '../utils/scraper-cache.js';
+/**
+ * Base provider with common functionality
+ */
+export class BaseLegislationProvider {
+    cache;
+    rateLimiter;
+    jurisdiction;
+    displayName;
+    constructor(jurisdiction, displayName, rateLimitOptions, cacheOptions) {
+        this.jurisdiction = jurisdiction;
+        this.displayName = displayName;
+        this.rateLimiter = new RateLimiter(rateLimitOptions);
+        this.cache = new ScraperCache({
+            jurisdiction,
+            ...cacheOptions,
+        });
+    }
+    /**
+     * Get jurisdiction identifier
+     */
+    getJurisdiction() {
+        return this.jurisdiction;
+    }
+    /**
+     * Get display name
+     */
+    getDisplayName() {
+        return this.displayName;
+    }
+    /**
+     * Search with caching and rate limiting
+     */
+    async search(params) {
+        await this.rateLimiter.throttle();
+        const cacheKey = `search:${JSON.stringify(params)}`;
+        const results = await this.cache.getOrSet(cacheKey, async () => this.searchImpl(params), 30 * 60 * 1000); // 30 minute cache for search
+        return results;
+    }
+    /**
+     * Get work with caching and rate limiting
+     */
+    async getWork(workId) {
+        await this.rateLimiter.throttle();
+        const cacheKey = `work:${workId}`;
+        const work = await this.cache.getOrSet(cacheKey, async () => this.getWorkImpl(workId), 24 * 60 * 60 * 1000); // 24 hour cache for work details
+        return work;
+    }
+    /**
+     * Get versions with caching
+     */
+    async getVersions(workId) {
+        await this.rateLimiter.throttle();
+        const cacheKey = `versions:${workId}`;
+        const versions = await this.cache.getOrSet(cacheKey, async () => this.getVersionsImpl(workId), 24 * 60 * 60 * 1000);
+        return versions;
+    }
+    /**
+     * Get version with caching
+     */
+    async getVersion(versionId) {
+        await this.rateLimiter.throttle();
+        const cacheKey = `version:${versionId}`;
+        const version = await this.cache.getOrSet(cacheKey, async () => this.getVersionImpl(versionId), 24 * 60 * 60 * 1000);
+        return version;
+    }
+    /**
+     * Generate citation (default implementation)
+     */
+    getCitation(work, style) {
+        switch (style) {
+            case 'nzmj':
+                return this.generateNzmjCitation(work);
+            case 'apa':
+                return this.generateApaCitation(work);
+            case 'oscola':
+                return this.generateOscolaCitation(work);
+            case 'australian':
+                return this.generateAustralianCitation(work);
+            case 'bibtex':
+                return this.generateBibtexCitation(work);
+            case 'ris':
+                return this.generateRisCitation(work);
+            case 'enw':
+                return this.generateEnwCitation(work);
+        }
+        throw new Error(`Unknown citation style: ${String(style)}`);
+    }
+    /**
+     * Health check (from HealthCheckable)
+     */
+    async healthCheck() {
+        // Default: try a simple search
+        await this.searchImpl({ query: 'test', limit: 1 });
+    }
+    /**
+     * Get cache stats
+     */
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * Get rate limit status
+     */
+    getRateLimitStatus() {
+        return this.rateLimiter.getStatus();
+    }
+    // Citation generators
+    generateNzmjCitation(work) {
+        return `${work.title} ${work.year} (${work.jurisdiction})`;
+    }
+    generateApaCitation(work) {
+        return `${work.title}. (${work.year}). ${work.jurisdiction}.`;
+    }
+    generateOscolaCitation(work) {
+        return `${work.title} ${work.year} (${work.jurisdiction})`;
+    }
+    generateAustralianCitation(work) {
+        const suffix = work.jurisdiction === 'au-comm'
+            ? '(Cth)'
+            : work.jurisdiction === 'au-qld'
+                ? '(Qld)'
+                : `(${work.jurisdiction})`;
+        return `${work.title} ${suffix}`;
+    }
+    generateBibtexCitation(work) {
+        const year = this.getCitationYear(work);
+        const url = this.getCitationUrl(work);
+        return `@legislation{${work.work_id.replace(/[\\/]/g, '-')},
+  title = {${work.title}},
+  year = {${year}},
+  type = {${work.type}},
+  status = {${work.status}},
+  url = {${url}}
+}`;
+    }
+    generateRisCitation(work) {
+        const year = this.getCitationYear(work);
+        const url = this.getCitationUrl(work);
+        return `TY - LEG
+ID - ${work.work_id}
+TI - ${work.title}
+PY - ${year}
+M3 - ${work.type === 'act' ? 'Public Act' : work.type}
+CY - ${this.displayName}
+UR - ${url}
+ER - `;
+    }
+    generateEnwCitation(work) {
+        const year = this.getCitationYear(work);
+        const url = this.getCitationUrl(work);
+        return `%0 Statute
+%A ${this.displayName}
+%D ${year}
+%T ${work.title}
+%9 ${work.type === 'act' ? 'Public Act' : work.type}
+%U ${url}
+%Z ${work.work_id}`;
+    }
+    getCitationYear(work) {
+        if (work.year > 0) {
+            return String(work.year);
+        }
+        if (work.date) {
+            return work.date.substring(0, 4);
+        }
+        const match = work.work_id.match(/(?:^|[_/])((?:19|20)\d{2})(?:[_/]|$)/);
+        return match ? match[1] : '1900';
+    }
+    getCitationUrl(work) {
+        if (work.url) {
+            return work.url;
+        }
+        switch (work.jurisdiction) {
+            case 'nz':
+                return `https://www.legislation.govt.nz/${work.work_id.replace(/_/g, '/')}/`;
+            case 'au-comm':
+                return `https://www.legislation.gov.au/Details/${work.work_id}`;
+            case 'au-qld':
+                return `https://www.legislation.qld.gov.au/view/html/inforce/current/${work.work_id.replace(/\//g, '-')}`;
+            default:
+                return work.work_id;
+        }
+    }
+}
+/**
+ * Provider registry
+ *
+ * Manages multiple legislation providers and provides
+ * health monitoring across all jurisdictions.
+ */
+export class ProviderRegistry {
+    providers = new Map();
+    /**
+     * Register a provider
+     * @param provider - The legislation provider to register
+     */
+    register(provider) {
+        this.providers.set(provider.getJurisdiction(), provider);
+    }
+    /**
+     * Get provider by jurisdiction
+     * @param jurisdiction - The jurisdiction identifier
+     * @returns The provider or undefined if not found
+     */
+    get(jurisdiction) {
+        return this.providers.get(jurisdiction);
+    }
+    /**
+     * Get all providers
+     * @returns Array of all registered providers
+     */
+    getAll() {
+        return Array.from(this.providers.values());
+    }
+    /**
+     * Get all jurisdictions
+     * @returns Array of all jurisdiction identifiers
+     */
+    getJurisdictions() {
+        return Array.from(this.providers.keys());
+    }
+    /**
+     * Check if provider exists
+     * @param jurisdiction - The jurisdiction identifier
+     * @returns True if provider is registered
+     */
+    has(jurisdiction) {
+        return this.providers.has(jurisdiction);
+    }
+    /**
+     * Get health dashboard for all providers
+     */
+    async getHealthDashboard() {
+        const results = [];
+        for (const provider of this.providers.values()) {
+            try {
+                const status = await this.getProviderHealth(provider);
+                results.push({
+                    jurisdiction: provider.getJurisdiction(),
+                    healthy: status.healthy,
+                    status,
+                });
+            }
+            catch {
+                results.push({
+                    jurisdiction: provider.getJurisdiction(),
+                    healthy: false,
+                    status: {
+                        healthy: false,
+                        jurisdiction: provider.getJurisdiction(),
+                        lastSuccessfulScrape: null,
+                        lastCheck: new Date(),
+                        successRate: 0,
+                        averageResponseTime: 0,
+                        fallbackActive: false,
+                        consecutiveFailures: 1,
+                    },
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get health status for a provider
+     */
+    async getProviderHealth(provider) {
+        try {
+            await provider.healthCheck();
+            return {
+                healthy: true,
+                jurisdiction: provider.getJurisdiction(),
+                lastSuccessfulScrape: new Date(),
+                lastCheck: new Date(),
+                successRate: 100,
+                averageResponseTime: 0,
+                fallbackActive: false,
+                consecutiveFailures: 0,
+            };
+        }
+        catch {
+            return {
+                healthy: false,
+                jurisdiction: provider.getJurisdiction(),
+                lastSuccessfulScrape: null,
+                lastCheck: new Date(),
+                successRate: 0,
+                averageResponseTime: 0,
+                fallbackActive: false,
+                consecutiveFailures: 1,
+            };
+        }
+    }
+}
+/**
+ * Global provider registry instance
+ */
+const globalRegistry = new ProviderRegistry();
+export function getGlobalRegistry() {
+    return globalRegistry;
+}