apispain 1.0.0

package/README.md

@@ -0,0 +1,111 @@
+# apispain
+
+SDK oficial para la [API de datos públicos de España](https://apispain.es).
+
+Accede a licitaciones (PLACE), subvenciones (BDNS), sociedades (BORME) y normativa (BOE) con una sola librería.
+
+## Instalación
+
+```bash
+npm install apispain
+```
+
+## Inicio rápido
+
+```js
+import Apispain from 'apispain'
+
+const client = new Apispain({ apiKey: 'tu-api-key' })
+
+// Licitaciones abiertas
+const { data } = await client.place.getLicitaciones({ abiertas: true, limit: 10 })
+console.log(data[0].objeto)
+
+// Subvenciones por CCAA
+const subs = await client.bdns.getSubvenciones({ ccaa: 'Cataluña', limit: 5 })
+
+// Sociedad por ID
+const soc = await client.borme.getSociedadById('ES123456789')
+```
+
+## Constructor
+
+```js
+new Apispain({
+  apiKey: string,          // requerido
+  baseUrl: string,         // default: 'https://api.apispain.es/v1'
+  timeout: number,         // ms, default: 30000
+})
+```
+
+## Namespaces
+
+### `client.place` — Licitaciones (PLACE)
+
+| Método | Parámetros |
+|--------|-----------|
+| `getLicitaciones(params)` | `q`, `cpv`, `organo`, `abiertas`, `importeMin`, `importeMax`, `limit`, `cursor` |
+| `getLicitacionById(id)` | — |
+
+### `client.bdns` — Subvenciones (BDNS)
+
+| Método | Parámetros |
+|--------|-----------|
+| `getSubvenciones(params)` | `q`, `ccaa`, `sector`, `abiertas`, `importeMin`, `importeMax`, `limit`, `cursor` |
+| `getSubvencionById(id)` | — |
+
+### `client.borme` — Registro Mercantil
+
+| Método | Parámetros |
+|--------|-----------|
+| `getSociedades(params)` | `q`, `provincia`, `limit`, `cursor` |
+| `getSociedadById(id)` | — |
+| `getActos(params)` | `tipo`, `fechaDesde`, `limit`, `cursor` |
+
+### `client.boe` — Boletín Oficial del Estado
+
+| Método | Parámetros |
+|--------|-----------|
+| `getDocumentos(params)` | `q`, `seccion`, `fecha`, `limit`, `cursor` |
+| `getDocumentoById(id)` | — |
+
+### `client.webhooks`
+
+| Método | Descripción |
+|--------|-------------|
+| `list()` | Lista tus webhooks |
+| `create({ url, eventos })` | Crea un webhook |
+| `delete(id)` | Elimina un webhook |
+
+## Manejo de errores
+
+```js
+import { ApispainError } from 'apispain'
+
+try {
+  const data = await client.place.getLicitaciones({ limit: 20 })
+} catch (err) {
+  if (err instanceof ApispainError) {
+    console.error(err.status)   // 401, 429, 500...
+    console.error(err.message)  // mensaje legible
+    console.error(err.body)     // body JSON completo
+  }
+}
+```
+
+## Paginación
+
+Todas las listas devuelven `{ data, pagination: { nextCursor } }`. Pasa `cursor` en la siguiente llamada:
+
+```js
+let cursor
+do {
+  const res = await client.bdns.getSubvenciones({ limit: 100, cursor })
+  processar(res.data)
+  cursor = res.pagination.nextCursor
+} while (cursor)
+```
+
+## Licencia
+
+MIT

package/index.js

@@ -0,0 +1,98 @@
+/**
+ * apispain — SDK oficial para la API de datos públicos de España
+ * https://apispain.es
+ */
+
+export class ApispainError extends Error {
+  constructor(message, status, body) {
+    super(message)
+    this.name = 'ApispainError'
+    this.status = status
+    this.body = body
+  }
+}
+
+export class Apispain {
+  #apiKey
+  #baseUrl
+  #timeout
+
+  constructor({ apiKey, baseUrl = 'https://api.apispain.es/v1', timeout = 30000 } = {}) {
+    if (!apiKey) throw new Error('apiKey is required')
+    this.#apiKey = apiKey
+    this.#baseUrl = baseUrl.replace(/\/$/, '')
+    this.#timeout = timeout
+
+    this.borme = {
+      getSociedades: (params) => this.#request('/borme/sociedades', params),
+      getSociedadById: (id) => this.#request(`/borme/sociedades/${id}`),
+      getActos: (params) => this.#request('/borme/actos', params),
+    }
+
+    this.boe = {
+      getDocumentos: (params) => this.#request('/boe/documentos', params),
+      getDocumentoById: (id) => this.#request(`/boe/documentos/${id}`),
+    }
+
+    this.bdns = {
+      getSubvenciones: (params) => this.#request('/bdns/subvenciones', params),
+      getSubvencionById: (id) => this.#request(`/bdns/subvenciones/${id}`),
+    }
+
+    this.place = {
+      getLicitaciones: (params) => this.#request('/place/licitaciones', params),
+      getLicitacionById: (id) => this.#request(`/place/licitaciones/${id}`),
+    }
+
+    this.webhooks = {
+      list: () => this.#request('/webhooks'),
+      create: (body) => this.#request('/webhooks', null, 'POST', body),
+      delete: (id) => this.#request(`/webhooks/${id}`, null, 'DELETE'),
+    }
+  }
+
+  async #request(path, params = null, method = 'GET', body = null) {
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), this.#timeout)
+
+    let url = `${this.#baseUrl}${path}`
+    if (params) {
+      const qs = new URLSearchParams(
+        Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined && v !== null))
+      )
+      if (qs.toString()) url += `?${qs}`
+    }
+
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: {
+          'Authorization': `Bearer ${this.#apiKey}`,
+          'Content-Type': 'application/json',
+          'User-Agent': 'apispain-sdk/1.0.0',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      })
+
+      const data = await res.json().catch(() => ({}))
+
+      if (!res.ok) {
+        throw new ApispainError(
+          data?.message ?? `HTTP ${res.status}`,
+          res.status,
+          data
+        )
+      }
+
+      return data
+    } catch (err) {
+      if (err.name === 'AbortError') throw new ApispainError('Request timeout', 408, null)
+      throw err
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+}
+
+export default Apispain

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "apispain",
+  "version": "1.0.0",
+  "description": "SDK oficial para la API de datos públicos de España (BORME, BOE, BDNS, PLACE)",
+  "main": "index.js",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["spain", "api", "borme", "boe", "bdns", "place", "licitaciones", "subvenciones"],
+  "author": "apispain",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apispain/sdk"
+  }
+}

package/test.js

@@ -0,0 +1,49 @@
+import { Apispain, ApispainError } from './index.js'
+
+let passed = 0
+let failed = 0
+
+function ok(label) { console.log(`  ✓ ${label}`); passed++ }
+function fail(label, err) { console.log(`  ✗ ${label}: ${err}`); failed++ }
+
+// Test 1: constructor throws without apiKey
+try {
+  new Apispain()
+  fail('throws without apiKey', 'no error thrown')
+} catch (e) {
+  if (e.message === 'apiKey is required') ok('throws without apiKey')
+  else fail('throws without apiKey', e.message)
+}
+
+// Test 2: ApispainError has .status
+try {
+  const err = new ApispainError('test error', 401, { message: 'Unauthorized' })
+  if (err.status === 401 && err.name === 'ApispainError') ok('ApispainError has .status and .name')
+  else fail('ApispainError shape', `status=${err.status} name=${err.name}`)
+} catch (e) {
+  fail('ApispainError', e.message)
+}
+
+// Test 3: client instantiates correctly
+try {
+  const client = new Apispain({ apiKey: 'test-key' })
+  const hasAll = ['borme', 'boe', 'bdns', 'place', 'webhooks'].every(ns => typeof client[ns] === 'object')
+  if (hasAll) ok('client has all namespaces')
+  else fail('client namespaces', 'missing namespace')
+} catch (e) {
+  fail('client instantiation', e.message)
+}
+
+// Test 4: real API call with invalid key → 401 ApispainError
+console.log('\n  [network] testing real API with invalid key...')
+try {
+  const client = new Apispain({ apiKey: 'invalid-key-test', baseUrl: 'https://api.apispain.es/v1' })
+  await client.bdns.getSubvenciones({ limit: 1 })
+  fail('should throw on invalid key', 'no error thrown')
+} catch (e) {
+  if (e instanceof ApispainError && e.status === 401) ok(`real API returns 401 ApispainError (message: "${e.message}")`)
+  else fail('real API 401', `got ${e.constructor.name}: ${e.message}`)
+}
+
+console.log(`\n  ${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)