npm package: @integrius/sdk
Description: Official TypeScript SDK for the Integrius unified enterprise data platform
Author: Integrius
Latest version: 0.1.0

# @integrius/sdk

Official TypeScript SDK for the [Integrius](https://integri.us) unified enterprise data platform.

```bash
npm install @integrius/sdk
```

---

## Quick Start

```typescript
import { IntegriusClient } from '@integrius/sdk';

const integrius = new IntegriusClient({
  apiKey: process.env.INTEGRIUS_API_KEY!,
  organizationId: process.env.INTEGRIUS_ORG_ID!,
  baseUrl: 'https://api.integri.us', // or your self-hosted URL
});

// List all data sources
const sources = await integrius.dataSources.list();

// Query unified data across all systems (Enterprise — requires search scope)
const results = await integrius.search.query({
  q: 'acme corp',
  entity: 'customer',
});
```

---

## Configuration

```typescript
const integrius = new IntegriusClient({
  apiKey: 'igk_live_...',        // Required
  organizationId: 'org_...',     // Required for management endpoints
  baseUrl: 'https://api.integri.us', // Default — change for self-hosted
  timeout: 30_000,               // Optional, ms
});
```

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `apiKey` | ✅ | — | Your Integrius API key |
| `organizationId` | — | — | Your organisation ID. Required for most management endpoints |
| `baseUrl` | — | `https://api.integri.us` | Override for self-hosted instances |
| `timeout` | — | `30000` | Request timeout in milliseconds |

---

## Resources

### `dataSources`

Connect and manage data source connections (PostgreSQL, MySQL, Salesforce, APIs, etc.).

```typescript
// List all data sources
const sources = await integrius.dataSources.list();

// Get a specific data source
const source = await integrius.dataSources.get('ds_abc123');

// Create a new data source
const source = await integrius.dataSources.create({
  name: 'Production CRM',
  type: 'postgresql',
  config: {
    host: 'db.example.com',
    port: 5432,
    database: 'crm',
    username: 'readonly',
    password: 'secret',
  },
});

// Test connectivity
const result = await integrius.dataSources.test('ds_abc123');
// { success: true, latency_ms: 42 }

// Discover schema fields
const schema = await integrius.dataSources.discover('ds_abc123');
// { fields: [{ name: 'customer_id', type: 'integer', primary_key: true }, ...] }

// Update
await integrius.dataSources.update('ds_abc123', { name: 'Production CRM v2' });

// Delete
await integrius.dataSources.delete('ds_abc123');
```

Supported `type` values: `postgresql` · `mysql` · `mssql` · `sqlite` · `mongodb` · `snowflake` · `bigquery` · `redshift` · `salesforce` · `hubspot` · `rest_api` · `csv` · `excel`

---

### `applications`

Manage data products and integration applications.

```typescript
const apps = await integrius.applications.list();

const app = await integrius.applications.create({
  name: 'Customer 360',
  description: 'Unified customer view across CRM, ERP and support',
  type: 'data_product',
});

await integrius.applications.update(app.id, { status: 'active' });
await integrius.applications.delete(app.id);
```

---

### `consumers`

Manage the consumer registry — who or what is consuming your data products.

```typescript
const consumers = await integrius.consumers.list();

const consumer = await integrius.consumers.create({
  name: 'Analytics Dashboard',
  scope: 'shared',
});
```

`scope`: `public` · `shared` · `restricted`

---

### `search`

Federated search across all unified data products. **Requires Enterprise plan with search scope enabled.**

```typescript
// Search across all data products
const results = await integrius.search.query({ q: 'john smith' });

// Filter by entity type
const customers = await integrius.search.query({
  q: 'acme',
  entity: 'customer',
  limit: 10,
});

// Narrow to a specific data product
const results = await integrius.search.query({
  q: 'INV-2024',
  product_id: 'app_abc123',
});
```

Response shape:
```typescript
{
  results: [
    {
      entity_type: 'customer',
      entity_id: 'cust_001',
      product_id: 'app_abc123',
      product_name: 'Customer 360',
      fields: { name: 'Acme Corp', email: 'info@acme.com', ... },
      score: 0.97,
      source: 'salesforce',
    }
  ],
  meta: {
    total_results: 42,
    products_searched: 3,
    response_time_ms: 28,
    limit: 20,
    offset: 0,
  }
}
```

---

### `webhooks`

Subscribe to platform events.

```typescript
const webhook = await integrius.webhooks.create({
  url: 'https://your-app.com/hooks/integrius',
  events: ['data_source.test.failed', 'audit.alert'],
  secret: 'whsec_your_signing_secret',
});

// Test delivery
await integrius.webhooks.ping(webhook.id);

await integrius.webhooks.update(webhook.id, { active: false });
await integrius.webhooks.delete(webhook.id);
```

Available events: `data_source.created` · `data_source.updated` · `data_source.deleted` · `data_source.test.passed` · `data_source.test.failed` · `application.created` · `application.updated` · `application.deleted` · `consumer.created` · `audit.alert`

---

### `auditLog`

Query the immutable audit trail.

```typescript
const entries = await integrius.auditLog.list({
  resource_type: 'data_source',
  status: 'failure',
  from: '2025-01-01T00:00:00Z',
  to: '2025-12-31T23:59:59Z',
  limit: 50,
});
```

---

### `organizations`

```typescript
const org = await integrius.organizations.get();
await integrius.organizations.update({ name: 'Acme Corp' });
```

---

### `dependencies`

Get the full dependency graph — nodes and edges across data sources, applications, and consumers.

```typescript
const graph = await integrius.dependencies.graph();
// { nodes: [...], edges: [...] }
```

---

## Error Handling

All errors thrown are `IntegriusError` instances with a typed `code` and HTTP `status`:

```typescript
import { IntegriusClient, IntegriusError } from '@integrius/sdk';

try {
  const source = await integrius.dataSources.get('ds_notexist');
} catch (err) {
  if (err instanceof IntegriusError) {
    console.error(err.status);  // 404
    console.error(err.code);    // 'NOT_FOUND'
    console.error(err.message); // 'Data source not found'
  }
}
```

---

## TypeScript

The SDK is written in TypeScript and ships with full type definitions. No `@types/` package needed.

```typescript
import type { DataSource, SearchResult, Application } from '@integrius/sdk';
```

---

## Self-Hosted

Point `baseUrl` at your own Integrius instance:

```typescript
const integrius = new IntegriusClient({
  apiKey: process.env.INTEGRIUS_API_KEY!,
  organizationId: process.env.INTEGRIUS_ORG_ID!,
  baseUrl: 'https://integrius.your-company.com',
});
```

---

## Requirements

- Node.js 18+ (uses native `fetch`)
- TypeScript 5+ (if using TypeScript)

---

## Links

- [Integrius Platform](https://app.integri.us)
- [Documentation](https://integri.us/docs)
- [API Reference](https://app.integri.us/api/docs)