{"_id":"@andronics/charities-uk","_rev":"2-e2b787155e0cba630ff671695236ec4e","name":"@andronics/charities-uk","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.1":{"name":"@andronics/charities-uk","version":"1.0.1","keywords":["charity","uk","ccni","oscr","ccew","charity-commission","northern-ireland","scotland","england-wales","api-client","typescript"],"author":{"name":"andronics"},"license":"MIT","_id":"@andronics/charities-uk@1.0.1","maintainers":[{"name":"andronics","email":"andronics@gmail.com"}],"homepage":"https://github.com/andronics/charities-uk#readme","bugs":{"url":"https://github.com/andronics/charities-uk/issues"},"dist":{"shasum":"459c1a95c4f79468ada490d23a455b7833ca5680","tarball":"https://registry.npmjs.org/@andronics/charities-uk/-/charities-uk-1.0.1.tgz","fileCount":5,"integrity":"sha512-PRVHmcdNE05+GuT6PbaJp4s5e0NHD5oGAAbokE6LZ8xbw157JN+UFdm9q3odPMsRDjNtAhEL+wHCSKnB0Lan2Q==","signatures":[{"sig":"MEUCIQCpr8VZzNnpbOHh6a4VNT0vNTSmAV9QZyb760lRgTHsFAIgY7EyIunRZiM3DJcL9fcpRs+ryz9gHu+05Y48dxYH0UM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@andronics%2fcharities-uk@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":167143},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"0985e225841587c8c92b424da21d0b84bb36c043","scripts":{"lint":"eslint src/","test":"vitest","build":"tsup src/index.ts","lint:fix":"eslint src/ --fix","test:run":"vitest run","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"andronics","email":"andronics@gmail.com"},"repository":{"url":"git+https://github.com/andronics/charities-uk.git","type":"git"},"_npmVersion":"10.9.4","description":"TypeScript clients for UK Charity Commission APIs (CCEW, OSCR, CCNI)","directories":{},"_nodeVersion":"20.19.6","dependencies":{"lru-cache":"^10.4.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","husky":"^9.0.0","eslint":"^9.0.0","vitest":"^2.0.0","@eslint/js":"^9.0.0","typescript":"^5.3.0","@types/node":"^20.0.0","@commitlint/cli":"^20.0.0","semantic-release":"^24.0.0","typescript-eslint":"^8.0.0","@vitest/coverage-v8":"^2.0.0","@semantic-release/git":"^10.0.0","@semantic-release/changelog":"^6.0.0","@commitlint/config-conventional":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/charities-uk_1.0.1_1767473709482_0.5275226084791151","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@andronics/charities-uk","version":"1.0.2","description":"TypeScript clients for UK Charity Commission APIs (CCEW, OSCR, CCNI)","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"build":"tsup src/index.ts","typecheck":"tsc --noEmit","lint":"eslint src/","lint:fix":"eslint src/ --fix","test":"vitest","test:run":"vitest run","test:coverage":"vitest run --coverage","prepublishOnly":"npm run build"},"keywords":["charity","uk","ccni","oscr","ccew","charity-commission","northern-ireland","scotland","england-wales","api-client","typescript"],"author":{"name":"andronics"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/andronics/charities-uk.git"},"bugs":{"url":"https://github.com/andronics/charities-uk/issues"},"homepage":"https://github.com/andronics/charities-uk#readme","publishConfig":{"access":"public"},"engines":{"node":">=18.0.0"},"devDependencies":{"@commitlint/cli":"^20.0.0","@commitlint/config-conventional":"^20.0.0","@eslint/js":"^9.0.0","@semantic-release/changelog":"^6.0.0","@semantic-release/git":"^10.0.0","@types/node":"^20.0.0","@vitest/coverage-v8":"^2.0.0","eslint":"^9.0.0","husky":"^9.0.0","semantic-release":"^24.0.0","tsup":"^8.0.0","typescript":"^5.3.0","typescript-eslint":"^8.0.0","vitest":"^2.0.0"},"dependencies":{"lru-cache":"^10.4.3"},"_id":"@andronics/charities-uk@1.0.2","gitHead":"16411c34b58e73904e4ab313b8abbf4fc218801a","_nodeVersion":"20.19.6","_npmVersion":"10.9.4","dist":{"integrity":"sha512-K92xKON+3tfxhB14J2j4hxOv58TJPglbDWamNubPKguWE28s0uDASTiwkTSBAXP8LrDbdmbkJgb66UNMjfaKKw==","shasum":"2656305a138b93222144fd6a15890c40330ee972","tarball":"https://registry.npmjs.org/@andronics/charities-uk/-/charities-uk-1.0.2.tgz","fileCount":5,"unpackedSize":167179,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@andronics%2fcharities-uk@1.0.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCSvP6PM7kw+IVODUZHbo5kPRgR7mljdCV9mFdQ2bQmZQIgX8O+hEU4kpcLkT6ioIxvbBFLFDqsbpPA9F3FbFV8B3A="}]},"_npmUser":{"name":"andronics","email":"andronics@gmail.com"},"directories":{},"maintainers":[{"name":"andronics","email":"andronics@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/charities-uk_1.0.2_1767474518031_0.3824173378148763"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-03T20:55:09.408Z","modified":"2026-01-03T21:08:38.511Z","1.0.1":"2026-01-03T20:55:09.627Z","1.0.2":"2026-01-03T21:08:38.187Z"},"bugs":{"url":"https://github.com/andronics/charities-uk/issues"},"author":{"name":"andronics"},"license":"MIT","homepage":"https://github.com/andronics/charities-uk#readme","keywords":["charity","uk","ccni","oscr","ccew","charity-commission","northern-ireland","scotland","england-wales","api-client","typescript"],"repository":{"type":"git","url":"git+https://github.com/andronics/charities-uk.git"},"description":"TypeScript clients for UK Charity Commission APIs (CCEW, OSCR, CCNI)","maintainers":[{"name":"andronics","email":"andronics@gmail.com"}],"readme":"# @andronics/charities-uk\n\n[![CI](https://github.com/andronics/charities-uk/actions/workflows/ci.yml/badge.svg)](https://github.com/andronics/charities-uk/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@andronics/charities-uk.svg)](https://www.npmjs.com/package/@andronics/charities-uk)\n\nA TypeScript library for accessing UK charity regulator APIs with a unified, normalized interface.\n\n**This is a library, not a server.** Use it in your serverless functions, Express apps, or any Node.js environment.\n\n## Supported Regulators\n\n| Regulator | Jurisdiction | Authentication |\n|-----------|--------------|----------------|\n| **CCEW** | England & Wales | API key required |\n| **OSCR** | Scotland | API key required |\n| **CCNI** | Northern Ireland | None required |\n\n## Installation\n\n```bash\nnpm install @andronics/charities-uk\n```\n\n## Quick Start\n\n### CCNI (Charity Commission for Northern Ireland)\n\nNo API key required.\n\n```typescript\nimport { CCNIClient } from '@andronics/charities-uk';\n\nconst ccni = new CCNIClient();\n\n// Search for charities\nconst results = await ccni.search({ text: 'cancer' });\nconsole.log(`Found ${results.total} charities`);\n\n// Get charity details\nconst charity = await ccni.getCharity('100002');\nconsole.log(charity?.name); // \"Cancer Lifeline\"\n\n// Get trustees\nconst trustees = await ccni.getTrustees('100002');\n```\n\n### OSCR (Office of the Scottish Charity Regulator)\n\nRequires an API key from [OSCR](https://www.oscr.org.uk/about-charities/search-the-register/download-the-scottish-charity-register/oscr-public-apis/).\n\n```typescript\nimport { OSCRClient } from '@andronics/charities-uk';\n\nconst oscr = new OSCRClient({\n  apiKey: process.env.OSCR_API_KEY,\n});\n\n// Get all charities (paginated)\nconst results = await oscr.search({ page: 1 });\n\n// Get charity by SC number\nconst charity = await oscr.getCharity('SC000001');\n\n// Get charity with financial data from annual returns\nconst enriched = await oscr.getCharityWithFinancials('SC000001');\n\n// Get annual returns\nconst financials = await oscr.getAnnualReturns('SC000001');\n```\n\n### CCEW (Charity Commission for England and Wales)\n\nRequires an API key from the [CCEW Developer Portal](https://api-portal.charitycommission.gov.uk/).\n\n```typescript\nimport { CCEWClient } from '@andronics/charities-uk';\n\nconst ccew = new CCEWClient({\n  apiKey: process.env.CCEW_API_KEY,\n});\n\n// Search for charities\nconst results = await ccew.search({ text: 'cancer' });\n\n// Search by name specifically\nconst named = await ccew.searchByName('British Heart Foundation');\n\n// Get charity details\nconst charity = await ccew.getCharity('1234567');\n\n// Get trustees\nconst trustees = await ccew.getTrustees('1234567');\n\n// Get financial history\nconst financials = await ccew.getFinancialHistory('1234567');\n```\n\n## Configuration\n\nAll clients accept a configuration object:\n\n```typescript\ninterface ClientConfig {\n  /** API key (required for CCEW and OSCR) */\n  apiKey?: string;\n  /** Custom base URL (optional) */\n  baseUrl?: string;\n  /** Request timeout in milliseconds */\n  timeout?: number;           // Default: 30000\n  /** Number of retry attempts */\n  retryAttempts?: number;     // Default: 3\n  /** Base delay between retries */\n  retryDelay?: number;        // Default: 1000\n  /** Cache configuration */\n  cache?: {\n    enabled?: boolean;        // Default: true\n    ttl?: number;             // Default: 300000 (5 minutes)\n    maxSize?: number;         // Default: 100 entries\n  };\n}\n```\n\n### Example with caching configuration\n\n```typescript\nconst ccew = new CCEWClient({\n  apiKey: process.env.CCEW_API_KEY,\n  cache: {\n    enabled: true,\n    ttl: 10 * 60 * 1000,  // 10 minutes\n    maxSize: 200,\n  },\n});\n\n// First call hits API\nconst charity = await ccew.getCharity('1234567');\n\n// Second call served from cache\nconst trustees = await ccew.getTrustees('1234567');\n\n// Clear cache when needed\nccew.clearCache();\n```\n\n### Disable caching\n\n```typescript\nconst ccni = new CCNIClient({\n  cache: { enabled: false },\n});\n```\n\n## Normalized Charity Interface\n\nAll clients return a normalized `Charity` interface, regardless of source regulator:\n\n```typescript\ninterface Charity {\n  // Identifiers\n  id: string;                    // Full ID (NIC100002, SC000001, 1234567)\n  regulator: 'CCEW' | 'OSCR' | 'CCNI';\n  registrationNumber: string;\n  subsidiaryNumber?: string;\n  companyNumber?: string;\n\n  // Core info\n  name: string;\n  otherNames: string[];\n  status: 'ACTIVE' | 'REMOVED' | 'IN_DEFAULT' | 'LATE' | 'RECENTLY_REGISTERED';\n  registeredDate: Date | null;\n  removedDate: Date | null;\n\n  // Contact\n  website: string | null;\n  email: string | null;\n  phone: string | null;\n  address: string | null;\n\n  // Financial (latest year)\n  latestIncome: number | null;\n  latestExpenditure: number | null;\n  financialYearEnd: Date | null;\n\n  // People\n  employeeCount: number | null;\n  volunteerCount: number | null;\n  trusteeCount: number | null;\n\n  // Classification\n  purposes: string[];\n  beneficiaries: string[];\n  activities: string[];\n  areasOfOperation: string[];\n\n  // Governance\n  organisationType: string | null;\n  governingDocumentType: string | null;\n\n  // Extended text\n  charitableObjects: string | null;\n  publicBenefit: string | null;\n  activityDescription: string | null;\n\n  // Original API response (escape hatch)\n  _raw: unknown;\n}\n```\n\n## Error Handling\n\nThe library throws specific error types:\n\n```typescript\nimport {\n  CharityNotFoundError,\n  RateLimitError,\n  AuthenticationError,\n  NetworkError,\n  ApiError,\n} from '@andronics/charities-uk';\n\ntry {\n  const charity = await ccew.getCharity('1234567');\n} catch (error) {\n  if (error instanceof AuthenticationError) {\n    console.error('Invalid API key');\n  } else if (error instanceof RateLimitError) {\n    console.error(`Rate limited. Retry after: ${error.retryAfter}ms`);\n  } else if (error instanceof NetworkError) {\n    console.error('Network connectivity issue');\n  }\n}\n```\n\nNote: `getCharity()` returns `null` for not found instead of throwing.\n\n## Unified Interface\n\nAll clients implement the same method signatures for consistent usage across regulators:\n\n| Method | Description |\n|--------|-------------|\n| `search(query)` | Search charities |\n| `searchByName(name, page?)` | Search by charity name |\n| `getCharity(id)` | Get charity details |\n| `getTrustees(id)` | Get trustees |\n| `getFinancialHistory(id)` | Get financial years |\n| `getOtherRegulators(id)` | Get cross-regulator registrations |\n| `clearCache()` | Clear cached responses |\n\n### Feature Availability\n\nNot all regulators support all features. Unsupported methods return empty results and log a warning.\n\n| Method | CCEW | OSCR | CCNI |\n|--------|:----:|:----:|:----:|\n| `search()` | ✓ | ✓ Pagination only | ✓ |\n| `searchByName()` | ✓ | ⚠️ Not supported | ✓ |\n| `getCharity()` | ✓ | ✓ | ✓ |\n| `getTrustees()` | ✓ | ⚠️ Not supported | ✓ |\n| `getFinancialHistory()` | ✓ Multi-year | ✓ Via annual returns | ⚠️ Current year only |\n| `getOtherRegulators()` | ✓ | ⚠️ Not supported | ⚠️ Not supported |\n\n### Additional Client-Specific Methods\n\n**CCNIClient:**\n- `getCharityWithSubsidiary(regId, subId)` - Get subsidiary charity\n\n**OSCRClient:**\n- `getCharityWithFinancials(id)` - Get charity enriched with annual return data\n- `getAnnualReturns(id)` - Get raw annual returns\n\n**CCEWClient:**\n- `getCharityWithLinked(regId, linkedId)` - Get linked charity\n\n## Environment Variables\n\n```bash\n# Required for CCEW\nCCEW_API_KEY=your-ccew-api-key\n\n# Required for OSCR\nOSCR_API_KEY=your-oscr-api-key\n\n# CCNI requires no API key\n```\n\n## Requirements\n\n- Node.js >= 18.0.0\n- TypeScript >= 5.0 (for development)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}