npm package: @shadow-software/dabdash-rest
Description: TypeScript client for DabDash REST API - Type-safe cannabis dispensary management
Author: Shadow Software LLC
Latest version: 3.1.0

# @shadow-software/dabdash-rest

**Type-safe TypeScript client for the DabDash REST API**

Auto-generated from OpenAPI specification. Works with any WordPress site running the DabDash REST plugin.

[![npm version](https://badge.fury.io/js/@shadow-software%2Fdabdash-rest.svg)](https://www.npmjs.com/package/@shadow-software/dabdash-rest)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Features

- ✅ **100% Type-Safe** - Full TypeScript definitions for all 39 endpoints
- ✅ **Auto-Generated** - Always in sync with latest API spec
- ✅ **Zero Config** - Works out of the box with environment variables
- ✅ **JWT Authentication** - Built-in token management
- ✅ **IntelliSense Support** - Full autocomplete in your IDE
- ✅ **Fetch-Based** - Works in browser and Node.js
- ✅ **Tree-Shakeable** - Only bundle what you use

---

## Installation

```bash
npm install @shadow-software/dabdash-rest
```

Or with yarn:

```bash
yarn add @shadow-software/dabdash-rest
```

---

## Quick Start

### 1. Configure Environment

Create a `.env` file:

```env
VITE_DABDASH_API_BASE_URL=https://yoursite.com/wp-json/dabdash/v1
```

### 2. Use the Client

```typescript
import { OpenAPI, ProductsService, AuthService } from '@shadow-software/dabdash-rest';

// Configure base URL (automatic from env if using Vite)
OpenAPI.BASE = import.meta.env.VITE_DABDASH_API_BASE_URL;

// Get products
const products = await ProductsService.getProducts({
  strainType: 'hybrid',
  thcMin: 20,
  perPage: 12
});

// Login
const { tokens } = await AuthService.loginCustomer({
  requestBody: {
    email: 'user@example.com',
    password: 'password123'
  }
});

// Set JWT token for authenticated requests
OpenAPI.TOKEN = tokens.accessToken;

// Now all authenticated endpoints work
const customer = await LoyaltyService.getLoyaltyCustomer();
```

---

## Available Services

### **ProductsService**
```typescript
// Get products with filters
const response = await ProductsService.getProducts({
  page: 1,
  perPage: 12,
  strainType: 'indica' | 'sativa' | 'hybrid',
  thcMin: 20,
  thcMax: 30,
  zoneId: 1
});
```

### **AuthService**
```typescript
// Login
await AuthService.loginCustomer({ requestBody: { email, password } });

// Register
await AuthService.registerCustomer({ requestBody: { email, password, firstName, lastName } });

// Refresh token
await AuthService.refreshToken({ requestBody: { refreshToken } });

// Get current user
await AuthService.getCurrentUser();
```

### **ZonesService**
```typescript
// Get delivery zones
const zones = await ZonesService.getDeliveryZones();

// Get zones with polygon data
const zonesWithPolygons = await ZonesService.getDeliveryZonesWithPolygons();

// Check address eligibility
await ZonesService.checkDeliveryZone({
  requestBody: {
    address: '123 Main St',
    city: 'Halifax',
    postalCode: 'B3H 1A1'
  }
});
```

### **LoyaltyService**
```typescript
// Get customer loyalty data
const customer = await LoyaltyService.getLoyaltyCustomer();

console.log(customer.points);        // Type: number
console.log(customer.level?.name);   // Type: string | undefined
```

### **StoreService**
```typescript
// Get store info
const store = await StoreService.getStoreInfo();

console.log(store.name);              // Type: string
console.log(store.delivery);          // Type: DeliverySettings
console.log(store.currency.symbol);   // Type: string
```

### **SpendingGoalsService**
```typescript
// Get active campaigns
const campaigns = await SpendingGoalsService.getSpendingGoalCampaigns();
```

---

## Configuration

### Environment Variables

#### Vite
```env
VITE_DABDASH_API_BASE_URL=https://yoursite.com/wp-json/dabdash/v1
```

```typescript
OpenAPI.BASE = import.meta.env.VITE_DABDASH_API_BASE_URL;
```

#### Next.js
```env
NEXT_PUBLIC_DABDASH_API_BASE_URL=https://yoursite.com/wp-json/dabdash/v1
```

```typescript
OpenAPI.BASE = process.env.NEXT_PUBLIC_DABDASH_API_BASE_URL;
```

#### Plain Node.js
```env
DABDASH_API_BASE_URL=https://yoursite.com/wp-json/dabdash/v1
```

```typescript
import dotenv from 'dotenv';
dotenv.config();

OpenAPI.BASE = process.env.DABDASH_API_BASE_URL;
```

### Custom Headers

```typescript
import { OpenAPI } from '@shadow-software/dabdash-rest';

// Set zone ID for all requests
OpenAPI.HEADERS = {
  'X-DabDash-Zone-ID': '1'
};
```

---

## Type Definitions

All types are exported:

```typescript
import type {
  Product,
  DeliveryZone,
  LoyaltyCustomer,
  JWTTokens,
  CannabisStrain,
  StoreInfo
} from '@shadow-software/dabdash-rest';

const myProduct: Product = {
  id: 123,
  name: 'Blue Dream',
  cannabisStrain: {
    strainType: 'hybrid',
    thcPercentage: 22.5
  }
  // TypeScript enforces the complete type!
};
```

---

## Error Handling

```typescript
import { ApiError } from '@shadow-software/dabdash-rest';

try {
  const products = await ProductsService.getProducts();
} catch (error) {
  if (error instanceof ApiError) {
    console.error('Status:', error.status);   // HTTP status code
    console.error('Message:', error.message); // Error message
    console.error('Body:', error.body);       // Full response

    // Handle specific errors
    if (error.status === 401) {
      // Redirect to login
    }
  }
}
```

---

## React Example

```typescript
import { useState, useEffect } from 'react';
import { ProductsService, Product } from '@shadow-software/dabdash-rest';

function ProductList() {
  const [products, setProducts] = useState<Product[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function fetchProducts() {
      const response = await ProductsService.getProducts({
        strainType: 'hybrid',
        thcMin: 20
      });
      setProducts(response.data);
      setLoading(false);
    }

    fetchProducts();
  }, []);

  if (loading) return <div>Loading...</div>;

  return (
    <ul>
      {products.map(product => (
        <li key={product.id}>
          {product.name} - {product.cannabisStrain?.thcPercentage}% THC
        </li>
      ))}
    </ul>
  );
}
```

---

## API Coverage

| Module | Endpoints | Coverage |
|--------|-----------|----------|
| **Storefront** | 25 | ✅ 100% |
| **WPLoyalty** | 7 | ✅ 100% |
| **WooDelivery** | 3 | ✅ 100% |
| **WowRevenue** | 4 | ✅ 100% |
| **Total** | **39** | **✅ 100%** |

---

## Requirements

- **Node.js**: >= 16.0.0
- **TypeScript**: >= 5.0.0 (recommended)
- **DabDash REST Plugin**: >= 2.0.0

---

## License

MIT © Shadow Software LLC

---

## Links

- **Homepage**: https://dabdash.com
- **NPM Package**: https://www.npmjs.com/package/@shadow-software/dabdash-rest
- **GitHub**: https://github.com/shadow-software/dabdash-rest-api-extensions
- **API Documentation**: https://yoursite.com/wp-json/dabdash/v1/docs
- **Support**: https://dabdash.com/support

---

## Changelog

### 2.0.0 (2026-01-04)
- Initial release
- 100% type coverage
- All 39 endpoints supported
- Auto-generated from OpenAPI spec

---

*Auto-generated from OpenAPI specification*
*Maintained by Shadow Software LLC*