AusData SDK

Official TypeScript SDK for interacting with the AusData platform. Ship email content that matches AusData's design language and submit form data to app.ausdata.ai through a typed client.

Features

• Email templates – Modern, Minimal, Corporate, and Playful layouts with HTML + plaintext output.
• Rendering helpers – renderEmailHtml / renderEmailText convert structured payloads into ready-to-send markup.
• Template metadata – EmailTemplates.list() exposes the available presets for CMS/admin integrations.
• Forms API client – Ausdata.forms.submit authenticates with your AusData API key and calls /api/v1/forms/submit.
• Email API client – Ausdata.email.send triggers server-side delivery through /api/v1/emails/send.
• Business search client – Ausdata.business.search queries /api/v1/business/search to look up Australian business data by name or 11‑digit ABN.
• React UI Component – Ready-to-use business search interface with accordion layout, multiple themes, and responsive design.

Installation

npm install @ausdata/sdk
# or
pnpm add @ausdata/sdk

Configuration

⚠️ Security: API Key Management

CRITICAL: Never hardcode your API key in source code. Always store it as an environment variable.

# ✅ CORRECT: Store in environment variables
AUSDATA_API_KEY=sk_live_************************

# ❌ WRONG: Never do this!
const client = new Ausdata('sk_live_abc123...'); // DON'T DO THIS!

Environment Variables

The SDK supports multiple environment variable names for flexibility:

• AUSDATA_API_KEY (recommended for server-side)
• NEXT_PUBLIC_AUSDATA_API_KEY (for Next.js client-side, if needed)
• VITE_AUSDATA_API_KEY (for Vite applications)

Server-side usage (recommended):

# .env or .env.local (server-side only)
AUSDATA_API_KEY=sk_live_************************

Quick Start

Server-to-Server (S2S) Usage (Recommended for Backend)

The SDK is designed to work seamlessly in server environments (Node.js, Python with TypeScript, etc.).

Node.js / TypeScript

import { Ausdata } from '@ausdata/sdk';

// ✅ CORRECT: Read API key from environment variable
const apiKey = process.env.AUSDATA_API_KEY;
if (!apiKey) {
  throw new Error('AUSDATA_API_KEY environment variable is required');
}

const client = new Ausdata(apiKey);

// Use the client
const results = await client.business.search({ q: 'Sydney', limit: 10 });
console.log(results);

Using Server Utilities

The SDK provides helper functions to read API keys from environment variables:

import { Ausdata } from '@ausdata/sdk';
import { getApiKey, getBaseUrl } from '@ausdata/sdk/server';

// Automatically reads from AUSDATA_API_KEY, NEXT_PUBLIC_AUSDATA_API_KEY, or VITE_AUSDATA_API_KEY
const apiKey = getApiKey();
if (!apiKey) {
  throw new Error('API key not found. Please set AUSDATA_API_KEY environment variable.');
}

// Automatically reads from AUSDATA_BASE_URL or defaults to production URL
const baseUrl = getBaseUrl();

const client = new Ausdata(apiKey, { baseUrl });

Complete Server-Side Example

// server.ts or api.ts
import { Ausdata, AusdataError } from '@ausdata/sdk';
import { getApiKey } from '@ausdata/sdk/server';

// Initialize client (reads from environment)
const apiKey = getApiKey();
if (!apiKey) {
  throw new Error('AUSDATA_API_KEY environment variable is required');
}

const client = new Ausdata(apiKey);

// Example: Business search endpoint
export async function searchBusinesses(query: string) {
  try {
    const results = await client.business.search({ q: query, limit: 10 });
    return results;
  } catch (error) {
    if (error instanceof AusdataError) {
      console.error('AusData API Error:', error.code, error.message);
      throw error;
    }
    throw error;
  }
}

// Example: Send email
export async function sendNotificationEmail(to: string, subject: string, html: string) {
  try {
    const result = await client.email.send({
      to,
      subject,
      html,
      text: html.replace(/<[^>]*>/g, ''), // Simple HTML to text conversion
    });
    return result;
  } catch (error) {
    if (error instanceof AusdataError) {
      console.error('Email send failed:', error.code, error.message);
      throw error;
    }
    throw error;
  }
}

Python (Using TypeScript SDK via Node.js)

If you're using Python, you can call the SDK through Node.js:

# python_example.py
import subprocess
import json
import os

def search_businesses(query: str):
    """Call AusData SDK from Python via Node.js"""
    api_key = os.getenv('AUSDATA_API_KEY')
    if not api_key:
        raise ValueError('AUSDATA_API_KEY environment variable is required')
    
    script = f"""
    const {{ Ausdata }} = require('@ausdata/sdk');
    const client = new Ausdata('{api_key}');
    client.business.search({{ q: '{query}', limit: 10 }})
      .then(result => console.log(JSON.stringify(result)))
      .catch(error => {{ console.error(error); process.exit(1); }});
    """
    
    result = subprocess.run(
        ['node', '-e', script],
        capture_output=True,
        text=True
    )
    
    if result.returncode !== 0:
        raise RuntimeError(f"SDK call failed: {result.stderr}")
    
    return json.loads(result.stdout)

# Usage
results = search_businesses('Sydney')
print(results)

Ruby (Using TypeScript SDK via Node.js)

# ruby_example.rb
require 'json'
require 'open3'

def search_businesses(query)
  api_key = ENV['AUSDATA_API_KEY']
  raise 'AUSDATA_API_KEY environment variable is required' unless api_key
  
  script = <<~JS
    const { Ausdata } = require('@ausdata/sdk');
    const client = new Ausdata('#{api_key}');
    client.business.search({ q: '#{query}', limit: 10 })
      .then(result => console.log(JSON.stringify(result)))
      .catch(error => { console.error(error); process.exit(1); });
  JS
  
  stdout, stderr, status = Open3.capture3('node', '-e', script)
  
  raise "SDK call failed: #{stderr}" unless status.success?
  
  JSON.parse(stdout)
end

# Usage
results = search_businesses('Sydney')
puts results

React UI Components (Frontend - One Line!)

Business Search UI

import { AusdataUI } from '@ausdata/sdk/react';

export default function BusinessPage() {
  return <AusdataUI apiKey="your-api-key" />;
}

Features:

• Accordion Interface – Search form and display settings are organized in collapsible accordion panels for a cleaner, more organized interface
• Multiple Themes – Choose from 7 built-in themes: minimal, brand, light, dark, eye, cyan-blue, and violet-gold
• Layout Variants – Display results as table, card, or list views
• Business Search – Search by business name or 11-digit ABN with real-time results
• Responsive Design – Fully responsive and mobile-friendly
• Accessibility – Built with ARIA attributes and keyboard navigation support

Email UI Component

import { EmailUI } from '@ausdata/sdk/react';

export default function ContactPage() {
  return <EmailUI apiKey="your-api-key" />;
}

Features:

• Email Form – Complete email sending interface with HTML and text content support
• Auto Text Generation – Automatically generates plain text from HTML content
• Theme Support – Same 7 themes as Business Search UI
• Form Validation – Built-in validation for required fields
• Success/Error Handling – Clear feedback for successful sends and errors

Form UI Component

import { FormUI } from '@ausdata/sdk/react';

export default function ContactPage() {
  return (
    <FormUI 
      apiKey="your-api-key" 
      formId="contact-form"
      fields={[
        { name: 'name', label: 'Name', type: 'text', required: true },
        { name: 'email', label: 'Email', type: 'email', required: true },
        { name: 'message', label: 'Message', type: 'textarea', required: true },
      ]}
    />
  );
}

Features:

• Customizable Fields – Define your own form fields or use default contact form
• Field Validation – Built-in validation with custom validation functions
• Theme Support – Same 7 themes as other UI components
• Success/Error Callbacks – Optional callbacks for handling submission results
• Flexible Configuration – Support for text, email, tel, textarea, number, and url field types

SDK Usage (Server-Side)

import { Ausdata, renderEmailHtml, renderEmailText } from '@ausdata/sdk';

// ✅ CORRECT: Read from environment variable
const apiKey = process.env.AUSDATA_API_KEY;
if (!apiKey) {
  throw new Error('AUSDATA_API_KEY environment variable is required');
}

const client = new Ausdata(apiKey);

// 1. Render email content using AusData templates
const html = renderEmailHtml({
  name: 'Ada',
  email: '[email protected]',
  company: 'AusData',
  message: 'Requesting a demo',
}, { template: 'playful' });

const text = renderEmailText({
  name: 'Ada',
  email: '[email protected]',
  company: 'AusData',
  message: 'Requesting a demo',
});

// 2. Submit form data through AusData API
const submission = await client.forms.submit({
  formId: 'contact-form',
  data: { name: 'Ada', email: '[email protected]', message: 'Requesting a demo' },
});

// 3. Send a notification email via the AusData Email API
const email = await client.email.send({
  to: '[email protected]',
  subject: `New contact: ${submission.id}`,
  html,
  text,
});

console.log(submission.id, email.id);

// 4. Search Australian businesses by name
const searchByName = await client.business.search({ q: 'Sydney', limit: 10 });
console.log(searchByName.results);

// 5. Use the high-level BusinessModule for more expressive helpers
import { BusinessModule } from '@ausdata/sdk';
const business = new BusinessModule(client);

// 5.a Look up a single business by ABN (11-digit)
const entity = await business.lookupByAbn('60728711292');
console.log(entity?.name, entity?.abnStatus, entity?.gst, entity?.businessNames);

Both helpers automatically send Authorization: Bearer <api-key> to https://api.ausdata.app/api/v1. Override baseUrl for staging or self-hosted deployments:

// Custom base URL (e.g., for staging or self-hosted deployments)
const client = new Ausdata(apiKey, { 
  baseUrl: process.env.AUSDATA_BASE_URL || 'https://api.ausdata.app/api/v1' 
});

Server-Side Best Practices

1. Always use environment variables for API keys

   // ✅ Good
   const apiKey = process.env.AUSDATA_API_KEY;
      
   // ❌ Bad - Never hardcode
   const apiKey = 'sk_live_abc123...';

2. Validate API key presence

   const apiKey = process.env.AUSDATA_API_KEY;
   if (!apiKey) {
     throw new Error('AUSDATA_API_KEY environment variable is required');
   }

3. Use server utilities for automatic configuration

   import { getApiKey, getBaseUrl } from '@ausdata/sdk/server';
      
   const apiKey = getApiKey(); // Reads from multiple env var names
   const baseUrl = getBaseUrl(); // Reads from env or uses default

4. Handle errors appropriately

   try {
     const result = await client.business.search({ q: 'Sydney' });
   } catch (error) {
     if (error instanceof AusdataError) {
       // Handle API-specific errors
       console.error('API Error:', error.code, error.message);
     } else {
       // Handle network or other errors
       console.error('Request failed:', error);
     }
   }

API Surface

Templates

• renderEmailHtml(data, options) – returns HTML string.
• renderEmailText(data, options) – returns plaintext string.
• EmailTemplates.list() – returns the available template identifiers.

Client

• new Ausdata(apiKey, options?) – Create a new SDK instance
  • apiKey: string (required) – Your AusData API key
  • options?: { baseUrl?: string } (optional) – Custom base URL
• client.email.send(payload) – Send an email
• client.forms.submit(payload) – Submit form data
• client.business.search(params) – Search for businesses
• AusdataError – thrown when the API responds with non-2xx status or network errors

React Components

• <AusdataUI /> – Business search interface component
  • apiKey?: string – API key (or use environment variable)
  • baseUrl?: string – API base URL (default: '/api')
  • defaultTheme?: Theme – Initial theme
  • defaultVariant?: 'table' | 'card' | 'list' – Initial layout variant
  • showControlPanel?: boolean – Show theme/variant controls
  • title?: string – Page title
• <EmailUI /> – Email sending interface component
  • apiKey?: string – API key (or use environment variable)
  • baseUrl?: string – API base URL (default: '/api')
  • defaultTheme?: Theme – Initial theme
  • title?: string – Page title
  • defaultFromEmail?: string – Default sender email
  • defaultFromName?: string – Default sender name
  • showThemeSelector?: boolean – Show theme selector
• <FormUI /> – Form submission interface component
  • apiKey?: string – API key (or use environment variable)
  • formId: string – Form ID for submission (required)
  • baseUrl?: string – API base URL (default: '/api')
  • defaultTheme?: Theme – Initial theme
  • title?: string – Page title
  • fields?: FormField[] – Custom form fields
  • defaultFields?: boolean – Use default contact form fields (default: true)
  • showThemeSelector?: boolean – Show theme selector
  • onSuccess?: (submissionId: string) => void – Success callback
  • onError?: (error: Error) => void – Error callback

Types

All types from the API contract are exported:

• ApiErrorCode, ApiResponse
• SendEmailPayload, SendEmailResponseData
• SubmitFormPayload, SubmitFormResponseData
• SearchBusinessParams, BusinessEntity, SearchBusinessResponseData
• AusdataError

Error Handling

The SDK throws AusdataError instances when API requests fail:

import { Ausdata, AusdataError } from '@ausdata/sdk';

try {
  await client.email.send({ to: '[email protected]', subject: 'Test', html: '<p>Test</p>' });
} catch (error) {
  if (error instanceof AusdataError) {
    console.error('Error code:', error.code);
    console.error('Error message:', error.message);
    console.error('Error details:', error.details);
  }
}

Server-Side Integration Examples

Express.js

import express from 'express';
import { Ausdata } from '@ausdata/sdk';
import { getApiKey } from '@ausdata/sdk/server';

const app = express();
app.use(express.json());

// ✅ Read API key from environment variable
const apiKey = getApiKey();
if (!apiKey) {
  throw new Error('AUSDATA_API_KEY environment variable is required');
}

const client = new Ausdata(apiKey);

app.post('/api/search-business', async (req, res) => {
  try {
    const { query } = req.body;
    const results = await client.business.search({ q: query, limit: 10 });
    res.json(results);
  } catch (error) {
    res.status(500).json({ error: 'Search failed' });
  }
});

app.listen(3000);

Next.js API Route

// app/api/business-search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { Ausdata } from '@ausdata/sdk';
import { getApiKey } from '@ausdata/sdk/server';

export async function GET(request: NextRequest) {
  // ✅ Read API key from environment variable
  const apiKey = getApiKey();
  if (!apiKey) {
    return NextResponse.json(
      { error: 'API key not configured. Please set AUSDATA_API_KEY environment variable.' },
      { status: 500 }
    );
  }

  const client = new Ausdata(apiKey);
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get('q') || '';

  try {
    const results = await client.business.search({ q: query, limit: 10 });
    return NextResponse.json(results);
  } catch (error) {
    return NextResponse.json(
      { error: 'Search failed' },
      { status: 500 }
    );
  }
}

NestJS

// business.service.ts
import { Injectable } from '@nestjs/common';
import { Ausdata } from '@ausdata/sdk';
import { getApiKey } from '@ausdata/sdk/server';

@Injectable()
export class BusinessService {
  private client: Ausdata;

  constructor() {
    // ✅ Read API key from environment variable
    const apiKey = getApiKey();
    if (!apiKey) {
      throw new Error('AUSDATA_API_KEY environment variable is required');
    }
    this.client = new Ausdata(apiKey);
  }

  async searchBusinesses(query: string, limit = 10) {
    return this.client.business.search({ q: query, limit });
  }
}

Fastify

import Fastify from 'fastify';
import { Ausdata } from '@ausdata/sdk';
import { getApiKey } from '@ausdata/sdk/server';

const fastify = Fastify({ logger: true });

// ✅ Read API key from environment variable
const apiKey = getApiKey();
if (!apiKey) {
  throw new Error('AUSDATA_API_KEY environment variable is required');
}

const client = new Ausdata(apiKey);

fastify.post('/api/search-business', async (request, reply) => {
  try {
    const { query } = request.body as { query: string };
    const results = await client.business.search({ q: query, limit: 10 });
    return results;
  } catch (error) {
    reply.code(500).send({ error: 'Search failed' });
  }
});

fastify.listen({ port: 3000 });

Repository Layout

src/          # SDK source
src/templates # Email template implementations
src/server.ts # Server-side utilities (getApiKey, getBaseUrl, handleProxyRequest)
doc/          # Template & theme references
dist/         # Build artifacts (npm publish output)

Scripts

npm run lint   # ESLint over src/
npm run build  # tsup -> dist/
npm test       # Run test script

Contributing

1. Fork & clone this repo
2. npm install
3. npm run lint && npm run build
4. Submit a pull request with context (logs, screenshots, reproduction steps)

Issues & feature requests: open a GitHub issue or email support.

License

MIT © Ausdata Science

Support

• Publisher: Ausdata Science — [email protected]
• Technical Support: Ausdata Lab — [email protected]