# @texturehq/events

[![npm version](https://img.shields.io/npm/v/@texturehq/events.svg)](https://www.npmjs.com/package/@texturehq/events)

This package contains the official TypeScript definitions and [Zod](https://zod.dev/) schemas for all Texture webhook events. It's designed to help you build type-safe integrations with Texture's webhook system.

## Features

- Type definitions and [Zod](https://zod.dev/) schemas for all Texture webhook events
- Version-controlled event schemas with access to all historical versions
- Runtime validation using Zod
- Full TypeScript support

## Available Events

The following webhook events are supported:

### Device Events
- `device.connected` - Emitted when a device connects to Texture
- `device.disconnected` - Emitted when a device disconnects
- `device.discovered` - Emitted when a new device is discovered
- `device.updated` - Emitted when device properties are updated

### Command Events
- `command.succeeded` - Emitted when a device command completes successfully
- `command.failed` - Emitted when a device command fails

### Connection Events
- `connection.failed` - Emitted when a device connection attempt fails

### Customer Events
- `customer.created` - Emitted when a new customer is created
- `customer.updated` - Emitted when customer information is updated
- `customer.deleted` - Emitted when a customer is deleted

### Site Events
- `site.created` - Emitted when a new site is created
- `site.updated` - Emitted when site information is updated
- `site.deleted` - Emitted when a site is deleted

### Enrollment Events
- `enrollment.submitted` - Emitted when a new enrollment is submitted
- `enrollment.approved` - Emitted when an enrollment is approved
- `enrollment.rejected` - Emitted when an enrollment is rejected

## Installation

```bash
npm install @texturehq/events
# or
yarn add @texturehq/events
```

## Usage

### Latest Version

Each event type has a named export that always points to its latest version. This is the recommended way to use the package:

```typescript
import { DeviceConnectedEventSchema, DeviceConnectedEvent } from "@texturehq/events";

// Example webhook handler
const handleWebhook = (event: unknown) => {
  try {
    // Validate and type the event using latest version
    const parsedEvent = DeviceConnectedEventSchema.parse(event);
    
    // TypeScript knows this is a DeviceConnectedEvent
    console.log(parsedEvent.data.deviceId);
  } catch (error) {
    // Handle validation error
    console.error("Invalid event format", error);
  }
};
```

### Version-Specific Usage

All event schemas are versioned, and you can access any specific version directly. This is useful if you need to maintain compatibility with older event versions:

```typescript
import {
  DeviceConnectedEventSchema_1_0_0,  // Specific version
  DeviceConnectedEvent_1_0_0         // Type for specific version
} from "@texturehq/events";

// Use a specific version of the schema
const handleLegacyWebhook = (event: unknown) => {
  const parsedEvent = DeviceConnectedEventSchema_1_0_0.parse(event);
  // TypeScript knows this is specifically a DeviceConnectedEvent_1_0_0
};
```

When we make changes to an event schema, we:
1. Create a new versioned schema (e.g., `DeviceConnectedEventSchema_1_1_0`)
2. Update the main export (`DeviceConnectedEventSchema`) to point to the latest version
3. Maintain all previous versions for backwards compatibility

## Event Structure

All events follow a consistent structure:

```typescript
{
  type: string;      // The event type (e.g., "device.connected")
  version: string;   // The schema version (e.g., "1.0.0")
  data: {           // Event-specific payload
    // ... event specific fields
  }
}
```

For more details on these events and webhook integration, consult [our docs](https://docs.texturehq.com) or [contact us](https://www.texturehq.com/contact/).

## License

MIT