@cshah18/sdk 1.0.0

package/README.md

@@ -0,0 +1,454 @@
+# CoBuy Embedded SDK
+
+A lightweight, production-ready TypeScript SDK for embedding CoBuy's collaborative purchasing widget in your web applications. The SDK exposes a global `window.CoBuy` object that can be loaded via a `<script>` tag.
+
+## Features
+
+- 📦 **Lightweight**: ~7.5 KB (ESM, minified)
+- 🎯 **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- 🚀 **Easy Integration**: Simple `<script>` tag integration
+- ⚙️ **Configurable**: Support for multiple environments and theme customization
+- 🔧 **Well-Tested**: ESLint + TypeScript strict mode
+- 📝 **Documented**: Comprehensive JSDoc comments and examples
+
+## Installation
+
+### Via Script Tag (Browser)
+
+```html
+<script src="https://cdn.cobuy.app/cobuy-sdk.umd.js"></script>
+<script>
+  window.CoBuy.init({
+    merchantKey: "your-merchant-key",
+    env: "production",
+  });
+
+  window.CoBuy.renderWidget({
+    productId: "prod_123",
+    container: "#cobuy-widget",
+  });
+</script>
+```
+
+### Via NPM (for Module Bundlers)
+
+```bash
+npm install @cobuy/sdk
+```
+
+```typescript
+import CoBuy from "@cobuy/sdk";
+
+CoBuy.init({
+  merchantKey: "your-merchant-key",
+  env: "production",
+});
+
+CoBuy.renderWidget({
+  productId: "prod_123",
+  container: "#cobuy-widget",
+});
+```
+
+## Quick Start
+
+### 1. Initialize the SDK
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-unique-merchant-key",
+  env: "production", // or "local" for localhost:9000
+  debug: false,
+  theme: {
+    primaryColor: "#4f46e5",
+    textColor: "#1f2937",
+  },
+});
+```
+
+### 2. Render the Widget
+
+```typescript
+CoBuy.renderWidget({
+  productId: "prod_123",
+  container: "#widget-container", // CSS selector or HTMLElement
+  onCheckout: (data) => {
+    console.log("Checkout initiated:", data);
+  },
+  onError: (error) => {
+    console.error("Widget error:", error);
+  },
+  onOpen: () => {
+    console.log("Widget opened");
+  },
+  onClose: () => {
+    console.log("Widget closed");
+  },
+});
+```
+
+## API Reference
+
+### `CoBuy.init(options: CoBuyInitOptions): void`
+
+Initializes the SDK with configuration.
+
+**Parameters:**
+
+```typescript
+interface CoBuyInitOptions {
+  merchantKey: string; // Required: Your unique merchant key
+  env?: "production" | "local"; // Default: "production" (use "local" for localhost:9000)
+  theme?: {
+    primaryColor?: string; // e.g., "#4f46e5"
+    secondaryColor?: string;
+    textColor?: string;
+    borderRadius?: string;
+    fontFamily?: string;
+  };
+  debug?: boolean; // Default: false
+}
+```
+
+**Example:**
+
+```typescript
+CoBuy.init({
+  merchantKey: "pk_live_abc123xyz",
+  env: "production",
+  debug: false,
+  theme: {
+    primaryColor: "#4f46e5",
+    borderRadius: "8px",
+  },
+});
+```
+
+### `CoBuy.renderWidget(options: RenderWidgetOptions): void`
+
+Renders the CoBuy widget into a DOM container.
+
+**Parameters:**
+
+```typescript
+interface RenderWidgetOptions {
+  productId: string; // Required: The product to display
+  container: string | HTMLElement; // CSS selector or element
+  onCheckout?: (data: { groupId: string; productId: string }) => void;
+  onError?: (error: unknown) => void;
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+```
+
+**Example:**
+
+```typescript
+CoBuy.renderWidget({
+  productId: "prod_456",
+  container: "#cobuy-widget",
+  onCheckout: (data) => {
+    console.log(`Group ${data.groupId} checking out product ${data.productId}`);
+  },
+  onError: (error) => {
+    console.error("Checkout failed:", error);
+  },
+});
+```
+
+### `CoBuy.version: string`
+
+Returns the SDK version.
+
+```typescript
+console.log(CoBuy.version); // "1.0.0"
+```
+
+### `CoBuy.getApiClient(): ApiClient | null`
+
+Returns the initialized API client instance for making direct API calls.
+
+**Example:**
+
+```typescript
+const apiClient = CoBuy.getApiClient();
+if (apiClient) {
+  const rewardResponse = await apiClient.getProductReward("prod_123");
+  if (rewardResponse.success) {
+    console.log("Reward:", rewardResponse.data.reward);
+  }
+}
+```
+
+### `ApiClient.getProductReward(productId: string): Promise<ApiResponse<ProductRewardData>>`
+
+Retrieves reward information for a specific product.
+
+**Response Structure:**
+
+```typescript
+interface ProductRewardData {
+  productId: string;
+  reward: {
+    id: string;
+    name: string;
+    type: "percentage" | "fixed" | "points" | "cashback";
+    value: string;
+    description: string | null;
+    remaining_quantity: number;
+    total_quantity: number;
+    valid_from: string; // ISO 8601 date
+    valid_to: string; // ISO 8601 date
+    status: "active" | "inactive" | "expired";
+  };
+  eligibility: {
+    isEligible: boolean;
+    reason?: string;
+  };
+}
+```
+
+**Example:**
+
+```typescript
+const apiClient = CoBuy.getApiClient();
+const response = await apiClient.getProductReward("prod_123");
+
+if (response.success) {
+  const { reward, eligibility } = response.data;
+  if (eligibility.isEligible) {
+    console.log(`${reward.value}% ${reward.name}`);
+    console.log(`Valid until: ${reward.valid_to}`);
+  }
+} else {
+  console.error("Error:", response.error.message);
+}
+```
+
+## API Base URLs
+
+The SDK automatically selects the appropriate API endpoint based on the `env` parameter:
+
+| Environment  | API URL                         |
+| ------------ | ------------------------------- |
+| `production` | `https://api.cobuyza.co.za/api` |
+| `local`      | `http://localhost:9000/api`     |
+
+The backend URLs are managed internally by the SDK for security.
+
+## Error Handling
+
+The SDK includes custom error classes:
+
+### `CoBuyNotInitializedError`
+
+Thrown when attempting to use the SDK before calling `init()`.
+
+```typescript
+try {
+  CoBuy.renderWidget({
+    /* ... */
+  });
+} catch (error) {
+  if (error instanceof CoBuyNotInitializedError) {
+    console.error("SDK not initialized");
+  }
+}
+```
+
+### `CoBuyInvalidConfigError`
+
+Thrown when invalid configuration is provided to `init()`.
+
+```typescript
+try {
+  CoBuy.init({ merchantKey: "" }); // Invalid
+} catch (error) {
+  if (error instanceof CoBuyInvalidConfigError) {
+    console.error("Invalid configuration:", error.message);
+  }
+}
+```
+
+## Debugging
+
+Enable debug logging to monitor SDK operations:
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-key",
+  debug: true, // Enables console logging
+});
+```
+
+When debug mode is enabled, the SDK logs:
+
+- SDK initialization details
+- Environment and API base URL
+- Widget rendering operations
+
+## Project Structure
+
+```
+cobuy-sdk/
+├── src/
+│   ├── index.ts                 # Entry point, window.CoBuy export
+│   ├── core/
+│   │   ├── cobuy.ts            # Main SDK implementation
+│   │   ├── config.ts           # Configuration manager
+│   │   ├── logger.ts           # Logging utility
+│   │   ├── types.ts            # TypeScript type definitions
+│   │   └── errors.ts           # Custom error classes
+│   └── ui/
+│       └── widget/
+│           └── widget-root.ts  # Widget rendering logic
+├── dist/                        # Compiled output
+│   ├── cobuy-sdk.esm.js        # ES Module format
+│   ├── cobuy-sdk.esm.js.map    # Source map
+│   ├── cobuy-sdk.umd.js        # UMD format (browser globals)
+│   └── cobuy-sdk.umd.js.map    # Source map
+├── package.json
+├── tsconfig.json
+├── rollup.config.mjs
+└── eslint.config.js
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 16+
+- npm or yarn
+
+### Setup
+
+```bash
+npm install
+```
+
+### Scripts
+
+```bash
+# Build the SDK
+npm run build
+
+# Watch mode (rebuilds on file changes)
+npm run build:watch
+
+# Run ESLint
+npm run lint
+
+# Fix ESLint issues
+npm run lint:fix
+
+# Type check + lint
+npm run check
+```
+
+### Code Quality
+
+This project uses:
+
+- **TypeScript**: Strict mode enabled for type safety
+- **ESLint**: Enforces code standards
+- **Prettier**: Automatic code formatting
+- **Rollup**: Module bundler for optimized output
+
+### Building
+
+The SDK is built with Rollup and produces:
+
+1. **ESM Bundle** (`cobuy-sdk.esm.js`): For use with modern module bundlers
+2. **UMD Bundle** (`cobuy-sdk.umd.js`): For direct browser inclusion via `<script>` tag
+
+Type definitions are generated automatically and included in the `dist/types/` directory.
+
+## Browser Support
+
+- Modern browsers with ES2017+ support
+- Chrome 51+
+- Firefox 54+
+- Safari 10+
+- Edge 15+
+
+## TypeScript Support
+
+The SDK includes full TypeScript definitions. When using with TypeScript:
+
+```typescript
+import CoBuy from "@cobuy/sdk";
+import type { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions } from "@cobuy/sdk";
+
+// All types are available for import
+const options: CoBuyInitOptions = {
+  merchantKey: "key",
+  env: "production",
+};
+
+CoBuy.init(options);
+```
+
+## Configuration Examples
+
+### Minimal Configuration
+
+```typescript
+CoBuy.init({
+  merchantKey: "pk_live_123abc",
+});
+```
+
+### Full Configuration
+
+```typescript
+CoBuy.init({
+  merchantKey: "pk_live_123abc",
+  env: "production",
+  theme: {
+    primaryColor: "#4f46e5",
+    secondaryColor: "#e5e7eb",
+    textColor: "#1f2937",
+    borderRadius: "8px",
+    fontFamily: "'Inter', sans-serif",
+  },
+  debug: true,
+});
+```
+
+### With Event Handlers
+
+```typescript
+CoBuy.renderWidget({
+  productId: "prod_789",
+  container: "#my-widget",
+  onOpen: () => {
+    // Track analytics
+    analytics.track("cobuy_widget_opened");
+  },
+  onCheckout: (data) => {
+    // Send to your backend
+    api.post("/order/initiate", data);
+  },
+  onError: (error) => {
+    // Handle errors gracefully
+    showErrorNotification(error.message);
+  },
+  onClose: () => {
+    // Cleanup
+    console.log("Widget closed");
+  },
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues, feature requests, or questions, please contact support@cobuy.app or create an issue in the repository.
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: December 2025