law4devs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 law4devs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# law4devs
+
+Official TypeScript SDK for the [Law4Devs API](https://api.law4devs.eu) — structured EU regulatory compliance data for developers.
+
+[![npm version](https://img.shields.io/npm/v/law4devs.svg)](https://www.npmjs.com/package/law4devs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- Full TypeScript types for all API resources
+- Zero runtime dependencies (uses Node 18+ built-in `fetch`)
+- Automatic pagination with `AsyncGenerator` (`iter()`)
+- Automatic retry with exponential backoff on 429/5xx
+- Dual CJS + ESM output
+
+## Installation
+
+```bash
+npm install law4devs
+```
+
+## Quick Start
+
+```typescript
+import { Law4DevsClient } from 'law4devs';
+
+const client = new Law4DevsClient();
+
+// List all frameworks
+const page = await client.frameworks.list();
+console.log(page.data.map(f => f.slug));
+
+// Get a specific framework
+const gdpr = await client.frameworks.get('gdpr');
+console.log(gdpr.name, gdpr.requirementCount);
+
+// Iterate all articles in a framework (auto-pagination)
+for await (const article of client.articles.iter('gdpr')) {
+  console.log(article.articleNumber, article.title);
+}
+```
+
+## Authentication
+
+No API key is required for public endpoints. To use an API key:
+
+```typescript
+const client = new Law4DevsClient({ apiKey: 'your-key-here' });
+```
+
+## Configuration
+
+```typescript
+const client = new Law4DevsClient({
+  baseUrl: 'https://api.law4devs.eu/api/v1', // default
+  apiKey: 'optional-key',
+  timeout: 30_000,    // milliseconds, default 30s
+  maxRetries: 3,      // default 3
+});
+```
+
+## Resources
+
+### Frameworks
+
+```typescript
+// List frameworks (paginated)
+const page = await client.frameworks.list({ page: 1, perPage: 20 });
+
+// Get framework detail
+const fw = await client.frameworks.get('cra');
+
+// Iterate all frameworks (auto-pagination)
+for await (const fw of client.frameworks.iter()) {
+  console.log(fw.slug);
+}
+```
+
+### Articles
+
+```typescript
+// List articles in a framework
+const page = await client.articles.list('gdpr', { page: 1, perPage: 20 });
+
+// Get a specific article
+const article = await client.articles.get('gdpr', 5);
+
+// Get related articles
+const related = await client.articles.related('gdpr', 5);
+
+// Iterate all articles
+for await (const article of client.articles.iter('gdpr')) {
+  console.log(article.articleNumber, article.title);
+}
+```
+
+### Recitals
+
+```typescript
+const page = await client.recitals.list('gdpr');
+const recital = await client.recitals.get('gdpr', 1);
+for await (const r of client.recitals.iter('gdpr')) { /* ... */ }
+```
+
+### Requirements
+
+```typescript
+// All requirements
+const page = await client.requirements.list();
+
+// Filter by framework
+const gdprReqs = await client.requirements.list({ frameworkSlug: 'gdpr' });
+
+// Iterate
+for await (const req of client.requirements.iter({ frameworkSlug: 'gdpr' })) {
+  console.log(req.requirementText);
+}
+```
+
+### Tags
+
+```typescript
+const page = await client.tags.list();
+const tag = await client.tags.get('data-protection');
+for await (const tag of client.tags.iter()) { /* ... */ }
+```
+
+### Compliance Deadlines
+
+```typescript
+const page = await client.compliance.deadlines({ frameworkSlug: 'nis2' });
+for await (const d of client.compliance.iterDeadlines({ frameworkSlug: 'nis2' })) {
+  console.log(d.deadlineDate, d.description);
+}
+```
+
+### Annexes
+
+```typescript
+const page = await client.annexes.list('cra');
+const annex = await client.annexes.get('cra', 'I');
+for await (const annex of client.annexes.iter('cra')) { /* ... */ }
+```
+
+### Search
+
+```typescript
+const results = await client.search.query('data breach notification', {
+  framework: 'gdpr',
+  resultType: 'article',
+});
+
+for await (const result of client.search.iter('security requirements')) {
+  console.log(result.type, result.matchContext);
+}
+```
+
+## Pagination
+
+All `list()` methods return a `Page<T>` object:
+
+```typescript
+const page = await client.frameworks.list({ page: 1, perPage: 10 });
+console.log(page.meta.total);    // total items
+console.log(page.meta.pages);    // total pages
+console.log(page.links.next);    // URL of next page, or null
+console.log(page.data);          // array of items
+```
+
+For automatic iteration, use `iter()`:
+
+```typescript
+for await (const item of client.frameworks.iter({ perPage: 50 })) {
+  // Automatically fetches next page when needed
+}
+```
+
+## Error Handling
+
+```typescript
+import { Law4DevsClient, NotFoundError, RateLimitError, ValidationError } from 'law4devs';
+
+try {
+  const fw = await client.frameworks.get('unknown-slug');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.error('Framework not found:', err.message);
+  } else if (err instanceof RateLimitError) {
+    console.error('Rate limited — will retry automatically');
+  } else if (err instanceof ValidationError) {
+    console.error('Bad request:', err.message, err.statusCode);
+  }
+}
+```
+
+Error classes: `Law4DevsError` (base), `NotFoundError`, `ValidationError`, `RateLimitError`, `ServerError`.
+
+## Available Frameworks
+
+| Slug | Name | CELEX | Status |
+|------|------|-------|--------|
+| `gdpr` | General Data Protection Regulation | 32016R0679 | Active |
+| `nis2` | Network and Information Security Directive 2 | 32022L2555 | Active |
+| `cra` | Cyber Resilience Act | 32024R2847 | Active |
+| `ai-act` | Artificial Intelligence Act | 32024R1689 | Active |
+| `dora` | Digital Operational Resilience Act | 32022R2554 | Active |
+| `dsa` | Digital Services Act | 32022R2065 | Active |
+| `dma` | Digital Markets Act | 32022R1925 | Active |
+| `eidas2` | eIDAS 2.0 | 32024R1183 | Active |
+| `data-act` | Data Act | 32023R2854 | Active |
+| `data-governance-act` | Data Governance Act | 32022R0868 | Active |
+| `eu-ai-liability` | EU AI Liability Directive | — | Active |
+| `product-liability` | Product Liability Directive | — | Active |
+| `eprivacy` | ePrivacy Regulation | — | Active |
+| `psd3` | Payment Services Directive 3 | — | Active |
+| `micar` | Markets in Crypto-Assets Regulation | 32023R1114 | Active |
+| `open-finance` | Open Finance Framework | — | Active |
+| `fida` | Financial Data Access | — | Active |
+| `nis1` | Network and Information Security Directive 1 | 32016L1148 | Superseded |
+| `csd-r` | Cyber Security Delegated Regulation | — | Active |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+declare const DEFAULT_BASE_URL = "https://api.law4devs.eu/api/v1";
+interface HTTPClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare class HTTPClient {
+    readonly baseUrl: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    readonly _headers: Record<string, string>;
+    constructor(options?: HTTPClientOptions);
+    get<T = unknown>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+}
+
+interface PageMeta {
+    apiVersion: string;
+    total: number;
+    page: number;
+    perPage: number;
+    pages: number;
+}
+interface PageLinks {
+    next: string | null;
+    prev: string | null;
+}
+interface Page<T> {
+    data: T[];
+    meta: PageMeta;
+    links: PageLinks;
+}
+
+declare abstract class BaseResource {
+    protected readonly _http: HTTPClient;
+    constructor(_http: HTTPClient);
+    protected parsePage<T>(raw: Record<string, unknown>, fromDict: (d: Record<string, unknown>) => T): Page<T>;
+    protected pageParams(page?: number, perPage?: number): Record<string, number | undefined>;
+    protected _iterPages<T>(listFn: (opts: {
+        page: number;
+        perPage: number;
+    }) => Promise<Page<T>>, perPage?: number): AsyncGenerator<T>;
+}
+
+interface Framework {
+    id: number;
+    slug: string;
+    name: string;
+    shortName: string;
+    celexNumber: string;
+    description: string | null;
+    isActive: boolean;
+    status: string;
+    expectedArticles: number;
+    expectedRecitals: number;
+    lastSyncedAt: string | null;
+    createdAt: string;
+    articleCount: number;
+    recitalCount: number;
+}
+interface FrameworkDetail extends Framework {
+    eurLexUrl: string;
+    requirementCount: number;
+    annexCount: number;
+    tagCount: number;
+    coverage: Record<string, unknown> | null;
+}
+
+declare class FrameworksResource extends BaseResource {
+    list(opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<Framework>>;
+    get(slug: string): Promise<FrameworkDetail>;
+    iter(opts?: {
+        perPage?: number;
+    }): AsyncGenerator<Framework>;
+}
+
+interface Tag {
+    id: number;
+    slug: string;
+    name: string;
+    description: string | null;
+    keywords: string[];
+    color: string | null;
+    createdAt: string;
+}
+
+interface ArticleParagraph {
+    paragraphRef: string;
+    content: string;
+    position: number;
+}
+interface ArticleSummary {
+    id: number;
+    frameworkSlug: string;
+    articleNumber: number;
+    title: string;
+    position: number;
+    paragraphCount: number;
+    tags: Tag[];
+}
+interface Article extends ArticleSummary {
+    content: string;
+    paragraphs: ArticleParagraph[];
+}
+
+declare class ArticlesResource extends BaseResource {
+    list(frameworkSlug: string, opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<ArticleSummary>>;
+    get(frameworkSlug: string, articleNumber: number | string): Promise<Article>;
+    related(frameworkSlug: string, articleNumber: number | string, opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<ArticleSummary>>;
+    iter(frameworkSlug: string, opts?: {
+        perPage?: number;
+    }): AsyncGenerator<ArticleSummary>;
+}
+
+interface Recital {
+    id: number;
+    frameworkSlug: string;
+    recitalNumber: number;
+    content: string;
+    position: number;
+}
+
+declare class RecitalsResource extends BaseResource {
+    list(frameworkSlug: string, opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<Recital>>;
+    get(frameworkSlug: string, recitalNumber: number | string): Promise<Recital>;
+    iter(frameworkSlug: string, opts?: {
+        perPage?: number;
+    }): AsyncGenerator<Recital>;
+}
+
+interface Requirement {
+    id: number;
+    frameworkSlug: string;
+    articleNumber: number | null;
+    paragraphRef: string | null;
+    paragraphContent: string | null;
+    requirementText: string;
+    requirementType: string;
+    complianceDeadline: string | null;
+    linkedArticleNumbers: number[];
+    stakeholderRoles: string[];
+    tags: Tag[];
+    createdAt: string;
+}
+
+declare class RequirementsResource extends BaseResource {
+    list(opts?: {
+        page?: number;
+        perPage?: number;
+        frameworkSlug?: string;
+    }): Promise<Page<Requirement>>;
+    iter(opts?: {
+        perPage?: number;
+        frameworkSlug?: string;
+    }): AsyncGenerator<Requirement>;
+}
+
+declare class TagsResource extends BaseResource {
+    list(opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<Tag>>;
+    get(slug: string): Promise<Tag>;
+    iter(opts?: {
+        perPage?: number;
+    }): AsyncGenerator<Tag>;
+}
+
+interface ComplianceDeadline {
+    id: number;
+    frameworkSlug: string;
+    articleNumber: string | null;
+    paragraphRef: string | null;
+    deadlineDate: string;
+    deadlineType: string;
+    description: string | null;
+}
+
+declare class ComplianceResource extends BaseResource {
+    deadlines(opts?: {
+        page?: number;
+        perPage?: number;
+        frameworkSlug?: string;
+    }): Promise<Page<ComplianceDeadline>>;
+    iterDeadlines(opts?: {
+        perPage?: number;
+        frameworkSlug?: string;
+    }): AsyncGenerator<ComplianceDeadline>;
+}
+
+interface AnnexSummary {
+    id: number;
+    frameworkSlug: string;
+    annexNumber: string;
+    title: string;
+}
+interface Annex extends AnnexSummary {
+    content: string;
+}
+
+declare class AnnexesResource extends BaseResource {
+    list(frameworkSlug: string, opts?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<AnnexSummary>>;
+    get(frameworkSlug: string, annexNumber: string): Promise<Annex>;
+    iter(frameworkSlug: string, opts?: {
+        perPage?: number;
+    }): AsyncGenerator<AnnexSummary>;
+}
+
+interface SearchResult {
+    type: string;
+    frameworkSlug: string;
+    frameworkName: string;
+    articleNumber: string | null;
+    recitalNumber: string | null;
+    paragraphRef: string | null;
+    title: string | null;
+    requirementType: string | null;
+    matchContext: string;
+    url: string;
+}
+
+declare class SearchResource extends BaseResource {
+    query(q: string, opts?: {
+        framework?: string;
+        resultType?: string;
+        page?: number;
+        perPage?: number;
+    }): Promise<Page<SearchResult>>;
+    iter(q: string, opts?: {
+        perPage?: number;
+        framework?: string;
+        resultType?: string;
+    }): AsyncGenerator<SearchResult>;
+}
+
+interface Law4DevsClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+declare class Law4DevsClient {
+    readonly _http: HTTPClient;
+    readonly frameworks: FrameworksResource;
+    readonly articles: ArticlesResource;
+    readonly recitals: RecitalsResource;
+    readonly requirements: RequirementsResource;
+    readonly tags: TagsResource;
+    readonly compliance: ComplianceResource;
+    readonly annexes: AnnexesResource;
+    readonly search: SearchResource;
+    constructor(options?: Law4DevsClientOptions);
+}
+
+declare class Law4DevsError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+declare class NotFoundError extends Law4DevsError {
+    constructor(msg: string, sc?: number);
+}
+declare class ValidationError extends Law4DevsError {
+    constructor(msg: string, sc?: number);
+}
+declare class RateLimitError extends Law4DevsError {
+    constructor(msg: string, sc?: number);
+}
+declare class ServerError extends Law4DevsError {
+    constructor(msg: string, sc?: number);
+}
+
+declare const VERSION = "0.1.0";
+
+export { type Annex, type AnnexSummary, AnnexesResource, type Article, type ArticleParagraph, type ArticleSummary, ArticlesResource, type ComplianceDeadline, ComplianceResource, DEFAULT_BASE_URL, type Framework, type FrameworkDetail, FrameworksResource, HTTPClient, type HTTPClientOptions, Law4DevsClient, type Law4DevsClientOptions, Law4DevsError, NotFoundError, type Page, type PageLinks, type PageMeta, RateLimitError, type Recital, RecitalsResource, type Requirement, RequirementsResource, SearchResource, type SearchResult, ServerError, type Tag, TagsResource, VERSION, ValidationError };