# SDK para TypeScript y JavaScript

Instala el SDK y haz una búsqueda en Node.js con TypeScript o JavaScript. Mantén la clave API en tu servidor.

Referencia canónica: https://flashdata.dev/es/docs/guides/flashdata-typescript
Revisado: 2026-11-04 por FlashData

- [GitHub](https://github.com/flashdatadev/flashdata-typescript) — Código fuente y referencia del SDK
- [Obtén una clave API](https://flashdata.dev/app/api-keys) — Crea una clave en la consola

<a id="application"></a>

## Haz tu primera solicitud con Node.js

Instala el paquete, configura tu clave API y elige TypeScript o JavaScript. Ejecuta el código en tu servidor o como script local.

- [Referencia de métodos del SDK](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/api-reference.md)
- [npm](https://www.npmjs.com/package/@flashdata-dev/sdk/v/1.1.0)

<a id="install"></a>

### Instala el SDK

Usa Node.js 22.18+ para ejecutar estos archivos directamente. Abre una terminal en una carpeta vacía y elige Nuevo proyecto. Si ya tienes un package.json, ejecuta la opción Proyecto existente desde ese directorio.

#### Nuevo proyecto

##### Instalar

```bash
npm init -y
npm install --save-exact @flashdata-dev/sdk@1.1.0
```


#### Proyecto existente

##### Instalar

```bash
npm install --save-exact @flashdata-dev/sdk@1.1.0
```


- [Instalar Node.js](https://nodejs.org/en/download)

<a id="key"></a>

### Configura la autenticación

Crea una clave API con permiso para Google Search o reutiliza una clave autorizada. Ejecuta el bloque y pega la clave cuando se solicite; no se mostrará en pantalla. Omite este paso si FLASHDATA_API_KEY ya está definida en tu entorno.

Los scripts leen FLASHDATA_API_KEY y la pasan al cliente; no cargan archivos .env. Usa la misma terminal para el paso 3. En una aplicación web, ejecuta este código en el servidor para mantener la clave fuera del navegador.

#### Bash

##### Clave API · Bash

```bash
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
```


#### PowerShell 7

##### Clave API · PowerShell

```powershell
# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey
```


- [Crear cuenta](https://flashdata.dev/signup)
- [Abrir API Keys](https://flashdata.dev/app/api-keys)
- [Abrir Billing](https://flashdata.dev/app/billing)
- [Configurar una prueba para agentes](https://flashdata.dev/es/docs/guides/agent-onboarding/reference.md)

<a id="query"></a>

### Haz una búsqueda

Elige TypeScript o JavaScript y guarda el código como quickstart.mts o quickstart.mjs, respectivamente, junto a package.json. Después ejecuta el comando que aparece debajo del script. Cada ejecución envía una búsqueda de hasta cinco resultados. Con Node.js 22.18+ no necesitas compilar estos ejemplos antes de ejecutarlos.

#### TypeScript

##### quickstart.mts

```typescript
import { FlashData, type GoogleSearchParams } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY in the server environment.');
const client = new FlashData({ apiKey });
const params: GoogleSearchParams = { num: 5 };
const response = await client.google.search({ query: 'battery recycling research', ...params });
if (response.status !== 'done') throw new Error(JSON.stringify(response));

for (const page of response.results) {
  for (const hit of page.organic ?? []) console.log(hit.title, hit.link);
}
console.log('Credits used:', response.usage.credits);
```

##### Ejecutar

```bash
node quickstart.mts
```


#### JavaScript

##### quickstart.mjs

```javascript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY in the server environment.');
const client = new FlashData({ apiKey });
const response = await client.google.search({ query: 'battery recycling research', num: 5 });
if (response.status !== 'done') throw new Error(JSON.stringify(response));

for (const page of response.results) {
  for (const hit of page.organic ?? []) console.log(hit.title, hit.link);
}
console.log('Credits used:', response.usage.credits);
```

##### Ejecutar

```bash
node quickstart.mjs
```



<a id="result"></a>

### Comprueba el resultado

El script comprueba que status sea done y termina sin errores. Verás los títulos y las URLs, seguidos de Credits used. Una lista organic vacía también es válida. La salida siguiente es ilustrativa; tu respuesta contiene los resultados y el consumo reales.

| Campo | Uso |
| --- | --- |
| results[].organic[] | Resultados de Google Search con campos como title, link y snippet. Cada fuente tiene su propia estructura de datos tipada. |
| usage.credits | Créditos consumidos por esta solicitud. Una búsqueda que devuelve cinco resultados se cuenta como una sola solicitud. |

#### Ejemplo de respuesta

```text
Battery recycling research https://example.org/recycling
Credits used: 0.02
```


<a id="common-tasks"></a>

## Prueba otra fuente de datos

Cada pestaña contiene un script completo que funciona en TypeScript y JavaScript. Sustituye el contenido del archivo del paso 3, conserva su extensión .mts o .mjs y usa el mismo comando para ejecutarlo. Cada ejecución envía una nueva solicitud; la clave debe tener el permiso indicado.

### Google News

Requiere el permiso google_news. La respuesta contiene las noticias en results[].news[].

#### quickstart.mts / quickstart.mjs

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.google.news({
  query: 'battery recycling', num: 5,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(response);
```


### Metadatos de YouTube

Requiere el permiso youtube_metadata. Devuelve el título, el canal, la duración y otros detalles del vídeo.

#### quickstart.mts / quickstart.mjs

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.youtube.metadata({
  video_id: 'dQw4w9WgXcQ', include_formats: false,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(response);
```


### Transcripción de YouTube

Requiere el permiso youtube_transcript. Solicita una pista de subtítulos automáticos en inglés que ya exista. Si está disponible, el texto se encuentra en results[].fullText.

#### quickstart.mts / quickstart.mjs

```typescript
import { FlashData } from '@flashdata-dev/sdk';

const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error('Set FLASHDATA_API_KEY first.');
const client = new FlashData({ apiKey });
const response = await client.youtube.transcript({
  video_id: 'dQw4w9WgXcQ', language: 'en', auto: true,
});
if (response.status !== 'done') throw new Error(JSON.stringify(response));
console.log(response);
```


- [Métodos y parámetros de todas las fuentes](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/sources/index.md)

<a id="typecheck"></a>

## Comprueba los tipos en TypeScript

Node.js elimina las anotaciones de tipos para ejecutar quickstart.mts, pero no comprueba los tipos. Para comprobarlos sin ejecutar el script ni enviar una solicitud, instala TypeScript y ejecuta el compilador con --noEmit desde el directorio del proyecto:

### Comprobar tipos

```bash
npm install --save-dev typescript@~5.9.3 @types/node@^22
npx tsc quickstart.mts --module nodenext --target es2022 --strict --noEmit
```

- [TypeScript en Node.js](https://nodejs.org/api/typescript.html)

<a id="features"></a>

## Funciones del SDK

| Uso | Métodos |
| --- | --- |
| google / youtube | Busca y recupera datos estructurados con métodos tipados para cada fuente. Reutiliza un cliente en tu servicio. |
| youtube.download | Envía un trabajo para entregar audio o vídeo en tu almacenamiento en la nube. Requiere el permiso youtube_download y la configuración del almacenamiento. |
| jobs / bulk | Guarda el ID del trabajo aceptado y recupera sus resultados cuando termine. await espera una promesa en JavaScript; mode: 'async' envía un trabajo en segundo plano al servidor. |
| account | Consulta el acceso, el saldo, los precios, los límites y el uso antes de ejecutar tareas recurrentes. |
| respondWith / accept | Pasa { respondWith: 'markdown' } como segundo argumento del método para obtener Markdown en response.content, o { accept: 'text/plain' } para obtener una cadena de texto. Por defecto, la respuesta JSON se devuelve como un objeto. |

- [Ejemplo completo de descarga](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/examples/youtube_download.mjs)
- [Configurar el almacenamiento para descargas](https://flashdata.dev/es/docs/guides/youtube-download-guide/reference.md)
- [Formatos de respuesta del SDK](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/response-formats.md)

<a id="next"></a>

## Siguientes pasos

- [Guardar resultados y gestionar errores](https://flashdata.dev/es/docs/guides/sdk-operations/reference.md)
- [Trabajos en segundo plano y solicitudes batch](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/jobs.md)
- [Configuración del cliente](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/client.md)
- [Referencia de métodos del SDK](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/api-reference.md)

<a id="errors"></a>

## Si un paso falla

| Problema | Qué hacer |
| --- | --- |
| Falta el paquete o la herramienta para ejecutarlo | Comprueba node --version y usa Node.js 22.18+ para estos ejemplos. Instala @flashdata-dev/sdk en el directorio que contiene package.json y conserva la extensión .mts o .mjs del archivo. |
| 401 / FLASHDATA_API_KEY | Define una clave válida en la terminal donde ejecutas el ejemplo. |
| 403 | Pide al titular que conceda el permiso de Google Search a esta clave API. |
| 402 | Consulta los créditos disponibles en Billing. Si la prueba del agente se ha agotado, vincúlala a una cuenta para obtener acceso del titular. |
| 429 | Espera el tiempo indicado por Retry-After y reduce la frecuencia de tus solicitudes. |
| Tiempo de espera agotado o error del servidor | Revisa History antes de volver a enviar la solicitud; la primera puede haberse ejecutado ya. |

- [Historial de solicitudes](https://flashdata.dev/app/jobs)
- [Facturación](https://flashdata.dev/app/billing)
- [Errores del SDK y recuperación](https://github.com/flashdatadev/flashdata-typescript/blob/v1.1.0/docs/errors.md)
