Usage Examples

Unified Contacts

Manage contacts across different source systems using a unified schema.

Create a Contact

import { LinksSDK, UnifiedContactRequest } from '@links/sdk';

const client = new LinksSDK({ apiKey: 'YOUR_API_KEY' });

const newContact: UnifiedContactRequest = {
  email: 'alice@example.com',
  first_name: 'Alice',
  last_name: 'Doe',
  phone: '+15550101',
  address: '123 Tech Lane',
  city: 'San Francisco',
  state: 'CA',
  // Optional: Link to a specific customer
  unified_customer_id: 'cust_98765'
};

const response = await client.unifiedContactsApi.createUnifiedContact(newContact);

console.log('Created Contact ID:', response.data.data.id);

{
  "data": {
    "id": "cont_12345",
    "email": "alice@example.com",
    "first_name": "Alice",
    "last_name": "Doe",
    "is_primary": true,
    "is_active": true,
    "created_at": "2024-01-15T10:00:00Z"
  }
}

List Contacts

Fetch a paginated list of contacts.

const response = await client.unifiedContactsApi.getPaginatedUnifiedContactList(
  1, // page
  20 // limit
);

const contacts = response.data.data;
console.log(`Retrieved ${contacts.length} contacts.`);

External Connections

Retrieve metadata about connected external systems, which is useful for building dynamic integrations.

List Connections

const connections = await client.externalConnectionApi.getExternalConnection(
  1, // Page
  20 // Limit
);

connections.data.data.forEach((conn) => {
  console.log(`Connection: ${conn.name} (Type: ${conn.type})`);
});

Get Connection Schema

Retrieve the database schema (tables and columns) for a specific external connection. This is often used to map fields dynamically.

const connectionId = "conn_abc123";

try {
  const schemaResponse =
    await client.externalConnectionApi.getExternalConnectionSchema(
      connectionId
    );
  const schema = schemaResponse.data;

  console.log("Available Columns:", schema);
  // Output: [{ column_name: 'id', data_type: 'uuid' }, { column_name: 'email', data_type: 'varchar' }]
} catch (error) {
  console.error("Failed to fetch schema:", error);
}

Error Handling

The SDK uses standard Axios errors. You can catch these to handle specific HTTP status codes or error messages.

import { isAxiosError } from "axios";

try {
  await client.unifiedInvoiceApi.getUnifiedInvoiceById("inv_non_existent");
} catch (error) {
  if (isAxiosError(error) && error.response) {
    // The request was made and the server responded with a status code
    // that falls out of the range of 2xx
    console.error(
      `Error ${error.response.status}: ${error.response.data.message}`
    );

    if (error.response.status === 404) {
      console.error("Invoice not found.");
    }
  } else {
    // Something happened in setting up the request that triggered an Error
    console.error("Network Error:", error);
  }
}