API Reference

Complete API documentation for the NZ Legislation Tool

Overview

This is the complete API reference for the NZ Legislation Tool. It includes all public functions, classes, interfaces, and types with examples and usage guidelines.

Generated from: TypeScript source code
Last Updated: 2026-03-10
Version: 1.0.0

Quick Links

Client API - Core API client methods
Commands API - Command implementations
Models & Types - TypeScript types and schemas
Output Formatters - Formatting utilities
Error Classes - Error handling
Configuration - Config management

Client API

Module: src/client.ts

Core API client for interacting with the NZ Legislation API.

`searchWorks(params: SearchParams): Promise<SearchResults>`

Search for legislation works matching the query parameters.

Parameters:

Name	Type	Required	Description
`params`	`SearchParams`	Yes	Search parameters object

SearchParams Interface:

interface SearchParams {
  query: string; // Search query (required)
  type?: 'act' | 'bill' | 'regulation' | 'instrument';
  status?: string; // e.g., 'in-force', 'repealed'
  from?: string; // ISO date: YYYY-MM-DD
  to?: string; // ISO date: YYYY-MM-DD
  limit?: number; // 1-100, default: 25
  offset?: number; // For pagination, default: 0
}

Returns: Promise<SearchResults>

SearchResults Interface:

interface SearchResults {
  total: number; // Total matching results
  offset: number; // Current offset
  limit: number; // Results per page
  works: Work[]; // Array of matching works
}

Throws:

ApiError - If API request fails
ValidationError - If parameters are invalid
RateLimitError - If rate limit exceeded

Example:

import { searchWorks } from '@client';

// Basic search
const results = await searchWorks({
  query: 'health',
  limit: 25,
});

console.log(`Found ${results.total} results`);
console.log(results.works);

// With filters
const filtered = await searchWorks({
  query: 'health',
  type: 'act',
  status: 'in-force',
  from: '2020-01-01',
  to: '2024-12-31',
  limit: 50,
});

Caching:

Results cached for 30 minutes
Cache key includes all parameters
LRU eviction (max 500 entries)

Rate Limiting:

Checks daily limit (10,000 requests)
Checks burst limit (2,000 requests/5min)
Includes 10% safety margin

`getWork(workId: string, options?: GetWorkOptions): Promise<Work>`

Get detailed information about a specific work by ID.

Parameters:

Name	Type	Required	Description
`workId`	`string`	Yes	Work ID (e.g., 'act/2020/67')
`options`	`GetWorkOptions`	No	Additional options

GetWorkOptions Interface:

interface GetWorkOptions {
  includeVersions?: boolean; // Include version history
  format?: 'json' | 'table'; // Output format
}

Returns: Promise<Work>

Work Interface:

interface Work {
  id: string;
  title: string;
  shortTitle?: string;
  type: 'act' | 'bill' | 'regulation' | 'instrument';
  status?: string;
  date: string;
  url: string;
  versionCount?: number;
  latestVersion?: {
    id: string;
    title: string;
    date: string;
  };
}

Throws:

ApiError - If work not found (404)
ValidationError - If workId format invalid

Example:

import { getWork } from '@client';

// Get work details
const work = await getWork('act/2020/67');
console.log(work.title);

// Include version history
const workWithVersions = await getWork('act/2020/67', {
  includeVersions: true,
});
console.log(`Has ${work.versionCount} versions`);

Caching:

Work details cached for 2 hours
Version history cached for 1 hour

`getWorkVersions(workId: string): Promise<Version[]>`

Get all versions of a specific work.

Parameters:

Name	Type	Required	Description
`workId`	`string`	Yes	Work ID

Returns: Promise<Version[]>

Version Interface:

interface Version {
  id: string;
  versionId: string;
  title: string;
  date: string;
  url: string;
  isCurrent: boolean;
}

Example:

import { getWorkVersions } from '@client';

const versions = await getWorkVersions('act/2020/67');
console.log(`Found ${versions.length} versions`);

// Find current version
const current = versions.find(v => v.isCurrent);
console.log(`Current: ${current.title}`);

`exportWorks(params: ExportParams): Promise<void>`

Export search results to a file.

Parameters:

Name	Type	Required	Description
`params`	`ExportParams`	Yes	Export parameters

ExportParams Interface:

interface ExportParams {
  query: string;
  output: string; // File path
  format?: 'csv' | 'json';
  type?: string;
  status?: string;
  from?: string;
  to?: string;
  limit?: number;
  includeMetadata?: boolean;
}

Returns: Promise<void>

Side Effects:

Creates file at specified path
Overwrites existing files

Example:

import { exportWorks } from '@client';

// Export to CSV
await exportWorks({
  query: 'health',
  output: 'health_acts.csv',
  format: 'csv',
  limit: 1000,
});

// Export to JSON with metadata
await exportWorks({
  query: 'health',
  output: 'health_acts.json',
  format: 'json',
  includeMetadata: true,
});

Metadata (when includeMetadata: true):

{
  "exportedAt": "2026-03-10T12:00:00Z",
  "query": "health",
  "totalResults": 42,
  "apiVersion": "v0",
  "toolVersion": "1.0.0"
}

`generateCitation(workId: string, style?: CitationStyle): Promise<string>`

Generate a citation for a specific work.

Parameters:

Name	Type	Required	Description
`workId`	`string`	Yes	Work ID
`style`	`CitationStyle`	No	Citation style (default: 'nzmj')

CitationStyle Type:

type CitationStyle = 'nzmj' | 'apa' | 'bibtex' | 'ris';

Returns: Promise<string> - Formatted citation

Example:

import { generateCitation } from '@client';

// NZMJ style (default)
const nzmj = await generateCitation('act/2020/67');
console.log(nzmj);
// Output: "Health Act 2020 (NZ) 2020/67."

// APA style
const apa = await generateCitation('act/2020/67', 'apa');
console.log(apa);
// Output: "Health Act 2020, Public Act 2020/67 (New Zealand)."

// BibTeX
const bibtex = await generateCitation('act/2020/67', 'bibtex');
console.log(bibtex);
// Output: @legislation{health2020, ...}

// RIS
const ris = await generateCitation('act/2020/67', 'ris');
console.log(ris);
// Output: TY - STATUTE ...

Commands API

Module: src/commands/

CLI command implementations.

`searchCommand`

Type: Command (from commander)

Search command configuration and handler.

Options:

interface SearchOptions {
  query: string;
  type?: string;
  status?: string;
  from?: string;
  to?: string;
  limit?: number;
  offset?: number;
  format?: 'table' | 'json' | 'csv';
  verbose?: boolean;
}

Usage:

nzlegislation search --query "health" --type act --limit 50

Handler:

async function searchHandler(options: SearchOptions) {
  try {
    const results = await searchWorks({
      query: options.query,
      type: options.type as SearchParams['type'],
      status: options.status,
      from: options.from,
      to: options.to,
      limit: options.limit,
      offset: options.offset,
    });

    console.log(formatOutput(results, options.format));
  } catch (error) {
    handleError(error);
  }
}

`getCommand`

Type: Command

Get command configuration and handler.

Options:

interface GetOptions {
  id: string;
  versions?: boolean;
  format?: 'table' | 'json' | 'csv';
  verbose?: boolean;
}

Usage:

nzlegislation get "act/2020/67" --versions

`exportCommand`

Type: Command

Export command configuration and handler.

Options:

interface ExportOptions {
  query: string;
  output: string;
  format?: 'csv' | 'json';
  type?: string;
  status?: string;
  limit?: number;
  includeMetadata?: boolean;
}

Usage:

nzlegislation export --query "health" --output results.csv --include-metadata

`citeCommand`

Type: Command

Cite command configuration and handler.

Options:

interface CiteOptions {
  id: string;
  style?: 'nzmj' | 'apa' | 'bibtex' | 'ris';
}

Usage:

nzlegislation cite "act/2020/67" --style apa

`configCommand`

Type: Command

Configuration command configuration and handler.

Options:

interface ConfigOptions {
  show?: boolean;
  key?: string;
  clear?: boolean;
}

Usage:

# Show current config
nzlegislation config --show

# Set API key
nzlegislation config --key YOUR_API_KEY

# Clear config
nzlegislation config --clear

Models & Types

Module: src/models/

TypeScript types and Zod schemas for validation.

WorkSchema

Type: ZodSchema<Work>

Schema for validating work objects.

Definition:

import { z } from 'zod';

export const WorkSchema = z.object({
  id: z.string(),
  title: z.string(),
  shortTitle: z.string().optional(),
  type: z.enum(['act', 'bill', 'regulation', 'instrument']),
  status: z.string().optional(),
  date: z.string(),
  url: z.string().url(),
  versionCount: z.number().optional(),
  latestVersion: z
    .object({
      id: z.string(),
      title: z.string(),
      date: z.string(),
    })
    .optional(),
});

export type Work = z.infer<typeof WorkSchema>;

Validation:

import { WorkSchema } from '@models';

// Validate work object
const result = WorkSchema.safeParse(apiResponse);

if (!result.success) {
  console.error('Validation failed:', result.error);
} else {
  console.log('Valid work:', result.data);
}

SearchParamsSchema

Type: ZodSchema<SearchParams>

Schema for validating search parameters.

Definition:

export const SearchParamsSchema = z.object({
  query: z.string().min(1, 'Query is required'),
  type: z.enum(['act', 'bill', 'regulation', 'instrument']).optional(),
  status: z.string().optional(),
  from: z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Invalid date format')
    .optional(),
  to: z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Invalid date format')
    .optional(),
  limit: z.number().min(1).max(100).default(25),
  offset: z.number().min(0).default(0),
});

SearchResultsSchema

Type: ZodSchema<SearchResults>

Schema for validating search results.

Definition:

export const SearchResultsSchema = z.object({
  total: z.number(),
  offset: z.number(),
  limit: z.number(),
  works: z.array(WorkSchema),
});

ConfigSchema

Type: ZodSchema<Config>

Schema for validating configuration.

Definition:

export const ConfigSchema = z.object({
  apiKey: z.string().min(1, 'API key is required'),
  baseUrl: z.string().url().default('https://api.legislation.govt.nz'),
  timeout: z.number().positive().default(30000),
  dailyLimit: z.number().positive().default(10000),
  burstLimit: z.number().positive().default(2000),
  safetyMargin: z.number().min(0).max(1).default(0.1),
});

Output Formatters

Module: src/output/

Utilities for formatting output.

`formatAsTable(results: SearchResults): string`

Format search results as a pretty table.

Parameters:

Name	Type	Description
`results`	`SearchResults`	Search results to format

Returns: string - Formatted table

Example:

import { formatAsTable } from '@output/formatters';

const table = formatAsTable(results);
console.log(table);

Output:

┌────────────────────┬──────────────────────────────────────────┬────────┬──────────┬────────────┐
│ ID                 │ Title                                    │ Type   │ Status   │ Date       │
├────────────────────┼──────────────────────────────────────────┼────────┼──────────┼────────────┤
│ act/2020/67        │ Health Act 2020                          │ act    │ in-force │ 2020-11-15 │
└────────────────────┴──────────────────────────────────────────┴────────┴──────────┴────────────┘

`formatAsJson(results: SearchResults): string`

Format search results as JSON.

Parameters:

Name	Type	Description
`results`	`SearchResults`	Search results to format

Returns: string - JSON string

Example:

import { formatAsJson } from '@output/formatters';

const json = formatAsJson(results);
console.log(json);

Output:

{
  "total": 42,
  "offset": 0,
  "limit": 25,
  "works": [...]
}

`formatAsCsv(results: SearchResults): string`

Format search results as CSV.

Parameters:

Name	Type	Description
`results`	`SearchResults`	Search results to format

Returns: string - CSV string

Example:

import { formatAsCsv } from '@output/formatters';

const csv = formatAsCsv(results);
console.log(csv);

Output:

id,title,shortTitle,type,status,date,url,versionCount
act/2020/67,Health Act 2020,Health Act 2020,act,in-force,2020-11-15,https://...,5

`generateCitation(work: Work, style: CitationStyle): string`

Generate a citation in the specified style.

Parameters:

Name	Type	Description
`work`	`Work`	Work to cite
`style`	`CitationStyle`	Citation style

Returns: string - Formatted citation

Supported Styles:

nzmj - New Zealand Medical Journal
apa - APA 7th edition
bibtex - BibTeX format
ris - RIS format

Example:

import { generateCitation } from '@output/citations';

const citation = generateCitation(work, 'apa');
console.log(citation);

Error Classes

Module: src/errors.ts

Error classes for error handling.

`ApplicationError`

Base class for all application errors.

Properties:

message: string - Error message
code: ErrorCode - Error code
suggestion?: string - Suggested fix

Example:

import { ApplicationError, ErrorCode } from '@errors';

throw new ApplicationError(
  'API key not configured',
  ErrorCode.CONFIG_API_KEY_MISSING,
  'Run: nzlegislation config --key YOUR_KEY'
);

`ApiError`

Error for API-related issues.

Extends: ApplicationError

Properties:

statusCode?: number - HTTP status code

Example:

import { ApiError } from '@errors';

throw new ApiError('Authentication failed', 401);

`ConfigError`

Error for configuration issues.

Extends: ApplicationError

Example:

import { ConfigError } from '@errors';

throw new ConfigError('Configuration file not found');

`ValidationError`

Error for validation failures.

Extends: ApplicationError

Example:

import { ValidationError } from '@errors';

throw new ValidationError('Invalid date format. Use YYYY-MM-DD');

`RateLimitError`

Error for rate limit exceeded.

Extends: ApplicationError

Properties:

retryAfter?: number - Seconds to wait

Example:

import { RateLimitError } from '@errors';

throw new RateLimitError('Rate limit exceeded. Please wait 300 seconds.', 300);

ErrorCode Enum

All error codes:

enum ErrorCode {
  // Configuration errors (1000-1999)
  CONFIG_API_KEY_MISSING = 1001,
  CONFIG_NOT_FOUND = 1002,

  // API errors (2000-2999)
  API_AUTHENTICATION_FAILED = 2001,
  API_NOT_FOUND = 2002,
  API_RATE_LIMIT_EXCEEDED = 2003,
  API_TIMEOUT = 2004,
  API_NETWORK_ERROR = 2005,

  // Validation errors (3000-3999)
  VALIDATION_INVALID_FORMAT = 3001,
  VALIDATION_REQUIRED_FIELD = 3002,
  VALIDATION_INVALID_DATE = 3003,

  // File errors (4000-4999)
  FILE_NOT_FOUND = 4001,
  FILE_WRITE_ERROR = 4002,
  FILE_READ_ERROR = 4003,

  // Network errors (5000-5999)
  NETWORK_ERROR = 5001,
  NETWORK_TIMEOUT = 5002,
  NETWORK_DNS_ERROR = 5003,
}

Configuration

Module: src/config.ts

Configuration management utilities.

`getConfig(): Promise<Config>`

Get current configuration.

Returns: Promise<Config>

Example:

import { getConfig } from '@config';

const config = await getConfig();
console.log(`API Key: ${maskApiKey(config.apiKey)}`);
console.log(`Base URL: ${config.baseUrl}`);

`setConfig(updates: Partial<Config>): Promise<Config>`

Update configuration.

Parameters:

Name	Type	Description
`updates`	`Partial<Config>`	Configuration updates

Returns: Promise<Config> - Updated configuration

Example:

import { setConfig } from '@config';

const config = await setConfig({
  apiKey: 'nzlapi3f4dd302e30beef18911',
});

`clearConfig(): Promise<void>`

Clear all configuration.

Returns: Promise<void>

Example:

import { clearConfig } from '@config';

await clearConfig();
console.log('Configuration cleared');

`validateConfig(config: unknown): Config`

Validate configuration object.

Parameters:

Name	Type	Description
`config`	`unknown`	Configuration to validate

Returns: Config - Validated configuration

Throws: ConfigError if validation fails

Example:

import { validateConfig } from '@config';

try {
  const config = validateConfig(rawConfig);
} catch (error) {
  console.error('Invalid config:', error);
}

Interactive Examples

Example 1: Basic Search

import { searchWorks } from '@client';
import { formatAsTable } from '@output/formatters';

async function basicSearch() {
  const results = await searchWorks({
    query: 'health',
    limit: 25,
  });

  console.log(formatAsTable(results));
}

basicSearch();

Example 2: Advanced Search with Filters

import { searchWorks } from '@client';
import { formatAsJson } from '@output/formatters';

async function advancedSearch() {
  const results = await searchWorks({
    query: 'health',
    type: 'act',
    status: 'in-force',
    from: '2020-01-01',
    to: '2024-12-31',
    limit: 100,
  });

  console.log(formatAsJson(results));
}

advancedSearch();

Example 3: Export to CSV

import { exportWorks } from '@client';

async function exportData() {
  await exportWorks({
    query: 'health',
    output: 'health_acts.csv',
    format: 'csv',
    limit: 1000,
    includeMetadata: true,
  });

  console.log('Export complete!');
}

exportData();

Example 4: Generate Citations

import { generateCitation } from '@client';

async function createBibliography() {
  const works = ['act/1981/118', 'act/2020/67', 'act/2000/7'];

  for (const workId of works) {
    const bibtex = await generateCitation(workId, 'bibtex');
    console.log(bibtex);
  }
}

createBibliography();

Example 5: Error Handling

import { searchWorks } from '@client';
import { ApiError, RateLimitError } from '@errors';

async function searchWithHandling() {
  try {
    const results = await searchWorks({ query: 'health' });
    console.log(results);
  } catch (error) {
    if (error instanceof RateLimitError) {
      console.log(`Rate limited. Wait ${error.retryAfter} seconds.`);
    } else if (error instanceof ApiError) {
      console.log(`API error: ${error.message}`);
      if (error.suggestion) {
        console.log(`Suggestion: ${error.suggestion}`);
      }
    } else {
      console.log('Unknown error:', error);
    }
  }
}

searchWithHandling();

FilesExpand file tree

api-reference.md

Latest commit

History

api-reference.md

File metadata and controls

API Reference

Overview

Quick Links

Client API

searchWorks(params: SearchParams): Promise<SearchResults>

getWork(workId: string, options?: GetWorkOptions): Promise<Work>

getWorkVersions(workId: string): Promise<Version[]>

exportWorks(params: ExportParams): Promise<void>

generateCitation(workId: string, style?: CitationStyle): Promise<string>

Commands API

searchCommand

getCommand

exportCommand

citeCommand

configCommand

Models & Types

WorkSchema

SearchParamsSchema

SearchResultsSchema

ConfigSchema

Output Formatters

formatAsTable(results: SearchResults): string

formatAsJson(results: SearchResults): string

formatAsCsv(results: SearchResults): string

generateCitation(work: Work, style: CitationStyle): string

Error Classes

ApplicationError

ApiError

ConfigError

ValidationError

RateLimitError

ErrorCode Enum

Configuration

getConfig(): Promise<Config>

setConfig(updates: Partial<Config>): Promise<Config>

clearConfig(): Promise<void>

validateConfig(config: unknown): Config

Interactive Examples

Example 1: Basic Search

Example 2: Advanced Search with Filters

Example 3: Export to CSV

Example 4: Generate Citations

Example 5: Error Handling

Related Documentation

`searchWorks(params: SearchParams): Promise<SearchResults>`

`getWork(workId: string, options?: GetWorkOptions): Promise<Work>`

`getWorkVersions(workId: string): Promise<Version[]>`

`exportWorks(params: ExportParams): Promise<void>`

`generateCitation(workId: string, style?: CitationStyle): Promise<string>`

`searchCommand`

`getCommand`

`exportCommand`

`citeCommand`

`configCommand`

`formatAsTable(results: SearchResults): string`

`formatAsJson(results: SearchResults): string`

`formatAsCsv(results: SearchResults): string`

`generateCitation(work: Work, style: CitationStyle): string`

`ApplicationError`

`ApiError`

`ConfigError`

`ValidationError`

`RateLimitError`

`getConfig(): Promise<Config>`

`setConfig(updates: Partial<Config>): Promise<Config>`

`clearConfig(): Promise<void>`

`validateConfig(config: unknown): Config`