> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de JavaScript

> Instala y usa el SDK oficial de JavaScript y TypeScript para la API de Profound

El SDK de JavaScript está publicado en npm como [@profoundai/client](https://www.npmjs.com/package/@profoundai/client). Incluye tipos de TypeScript.

## Instalación

```bash npm wrap theme={null}
npm install @profoundai/client
```

```bash yarn wrap theme={null}
yarn add @profoundai/client
```

```bash pnpm wrap theme={null}
pnpm add @profoundai/client
```

```bash bun wrap theme={null}
bun add @profoundai/client
```

## Inicio rápido

```typescript Create a client and run a report expandable wrap theme={null}
import Profound from '@profoundai/client';

const client = new Profound({
  apiKey: "your-api-key-here" // or set PROFOUND_API_KEY env var
});

// Get organization categories
const categories = await client.organizations.categories.list();
console.log(categories);

// Generate a report
const report = await client.reports.visibility({
  category_id: categories[0].id,
  start_date: "2024-01-01",
  end_date: "2024-01-31",
  dimensions: ["asset_name"],
  metrics: ["visibility_score"]
});
console.log(report);
```

## Autenticación

El SDK lee tu clave de API desde cualquiera de estas fuentes:

1. **Variable de entorno** (recomendado): define `PROFOUND_API_KEY` en tu entorno.
2. **Parámetro del constructor**: pasa `apiKey` al inicializar el cliente.

```bash Set the environment variable wrap theme={null}
export PROFOUND_API_KEY="your-api-key-here"
```

Para obtener más detalles sobre cómo conseguir una clave de API, consulta [Autenticación](https://docs.tryprofound.com/es/rest-api/authentication.md).

## Manejo de errores

```typescript Catch API errors expandable wrap theme={null}
import Profound from '@profoundai/client';

const client = new Profound();

try {
  const report = await client.reports.visibility({
    category_id: 'invalid-id',
    start_date: '2024-01-01',
    end_date: '2024-01-31',
    dimensions: ['asset_name'],
    metrics: ['visibility_score']
  });
} catch (error) {
  if (error instanceof Profound.APIError) {
    console.error(`API Error: ${error.status} - ${error.message}`);
  }
}
```

## Límites de solicitudes

La API tiene un límite predeterminado de 600 solicitudes por hora por clave de API. Cuando superas este límite, recibes un error `429 Too Many Requests`. El SDK lanza un error que puedes capturar y manejar.

```typescript Handle rate limits expandable wrap theme={null}
import Profound from '@profoundai/client';

try {
  const report = await client.reports.visibility(...);
} catch (error) {
  if (error instanceof Profound.RateLimitError) {
    console.log('Rate limit exceeded. Please wait before retrying.');
  }
}
```

## Compatibilidad asíncrona

El SDK se basa completamente en async/await. Todos los métodos devuelven promesas.

```typescript Await any method wrap theme={null}
import Profound from '@profoundai/client';

const client = new Profound();

const categories = await client.organizations.categories.list();
```

## Ejemplos de código

Cada endpoint de la documentación de la API incluye ejemplos funcionales en JavaScript. Explora la sección **Endpoints** en la pestaña REST API y SDKs para ver ejemplos de:

* Administración de organizaciones
* Descubrimiento de categorías
* Generación de informes
* Acceso a datos sin procesar

> [!TIP]
>
> Las interfaces del SDK pueden cambiar a medida que mejoramos la API. Fija una versión específica en entornos de producción.
