@tashie/sdk

TypeScript SDK for real-time webhook streaming on Tashie with full type safety.

Installation

npm install @tashie/hooked
# or
yarn add @tashie/hooked
# or
pnpm add @tashie/hooked

Usage

Basic Usage

Connecting to an instance:

import { createClient } from '@tashie/hooked';

const client = createClient({
  apiKey: 'your-api-key',
});

// Connect to start receiving webhooks
await client.connect();

// Listen to specific webhook slugs.
// These are the slugs that you generate on the dashboard.
client.on('payment-webhook', (webhook) => {
  console.log('Payment webhook received:', webhook.body);
});

// Listen to all webhooks
client.onAny((webhook) => {
  console.log(`Webhook [${webhook.slug}]:`, webhook.body);
});

// Error handling
client.onError((error) => {
  console.error('Error:', error);
});

// Later, disconnect
client.disconnect();

Advanced Usage (With Type Safety)

Define your webhook event map for full type safety:

import { createClient, WebhookEventMap } from '@tashie/hooked';

// Define your webhook event types
interface MyWebhookEvents extends WebhookEventMap {
  'payment-webhook': {
    amount: number;
    currency: string;
    status: 'success' | 'failed';
  };
}

// Create typed client
const client = createClient<MyWebhookEvents>({
  apiKey: 'your-api-key',
});

// Now you get full autocomplete and type checking!
client.on('payment-webhook', (webhook) => {
  // webhook.body is typed as { amount: number; currency: string; status: ... }
  console.log(`Payment of ${webhook.body.amount} ${webhook.body.currency}`);
});

client.on('user-created', (webhook) => {
  // webhook.body is typed as { id: string; email: string; name: string }
  console.log(`New user: ${webhook.body.email}`);
});

await client.connect();

Removing Listeners

// Define a handler
const paymentHandler = (webhook) => {
  console.log('Payment received:', webhook.body);
};

// Add listener
client.on('payment-webhook', paymentHandler);

// Remove specific handler
client.off('payment-webhook', paymentHandler);

// Remove all handlers for a slug
client.off('payment-webhook');

API Reference

createClient(config)

Factory function to create a new Tashie client.

Parameters:

• config.apiKey (required) - Your Tashie API key

Returns: TashieClient<TEvents>

TashieClient Methods

connect(): Promise<void>

Establish WebSocket connection to Tashie servers.

disconnect(): void

Close the WebSocket connection.

isConnected(): boolean

Check if currently connected.

on<K>(slug: K, handler: WebhookHandler<TEvents[K]>): void

Listen to webhooks for a specific slug. With type safety, slug autocompletes and handler receives typed webhook body.

onAny(handler: WebhookHandler<any>): void

Listen to all webhooks regardless of slug.

onError(handler: ErrorHandler): void

Register error handler for connection errors and parsing failures.

off<K>(slug: K, handler?: WebhookHandler<TEvents[K]>): void

Remove listener(s). If handler is provided, removes that specific handler. Otherwise removes all handlers for the slug.

Webhook Message Structure

interface WebhookMessage<T> {
  id: string;              // Unique message ID
  url_id: string;          // Webhook URL ID
  slug: string;            // Webhook slug (e.g., 'payment-webhook')
  method: string;          // HTTP method (GET, POST, etc.)
  headers: Record<string, string[]>;
  body: T;                 // Typed request body
  query_params: Record<string, string[]>;
  ip_address: string;
  content_type: string;
  created_at: string;      // ISO timestamp
}

Features

• ✅ Full TypeScript support with generics for type-safe webhooks
• ✅ Event-driven API with .on() handlers
• ✅ Automatic reconnection with exponential backoff
• ✅ Works in both Node.js and browser environments
• ✅ Multiple handlers per webhook slug
• ✅ Wildcard listener for all webhooks
• ✅ Proper error handling

License

MIT