@devwithbobby/loops 0.1.0 → 0.1.1

package/prds/CONTRIBUTING.md

@@ -1,274 +0,0 @@
-# Contributing to Convex Component Template
-
-Thank you for your interest in contributing! This document provides guidelines and instructions for contributing to this project.
-
-## Table of Contents
-
-- [Code of Conduct](#code-of-conduct)
-- [Getting Started](#getting-started)
-- [Development Workflow](#development-workflow)
-- [Coding Standards](#coding-standards)
-- [Testing](#testing)
-- [Submitting Changes](#submitting-changes)
-- [Release Process](#release-process)
-
-## Code of Conduct
-
-By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
-
-## Getting Started
-
-### Prerequisites
-
-- **Bun** (latest stable version)
-- **Node.js** 18+ (for Convex CLI)
-- **Git**
-
-### Setup
-
-1. Fork the repository on GitHub
-2. Clone your fork locally:
-   ```sh
-   git clone https://github.com/SamHoque/convex-component-template.git
-   cd convex-component-template
-   ```
-
-3. Install dependencies:
-   ```sh
-   bun install
-   ```
-
-4. Set up your Convex dev environment:
-   ```sh
-   bun run dev:backend
-   ```
-
-5. In another terminal, run the example app:
-   ```sh
-   bun run dev:frontend
-   ```
-
-## Development Workflow
-
-### Running the Dev Environment
-
-The project uses a multi-process development setup:
-
-```sh
-# Start all dev processes (backend, frontend, build watch)
-bun run dev
-
-# Or run individually:
-bun run dev:backend    # Convex dev server with live component sources
-bun run dev:frontend   # Example app with hot reload
-bun run build:watch    # TypeScript build in watch mode
-```
-
-### Making Changes
-
-1. Create a new branch for your feature or bugfix:
-   ```sh
-   git checkout -b feature/your-feature-name
-   ```
-
-2. Make your changes following the [coding standards](#coding-standards)
-
-3. Add tests for your changes in `test/component/`
-
-4. Run the test suite:
-   ```sh
-   bun test
-   ```
-
-5. Run linting and formatting:
-   ```sh
-   bun run check:fix
-   ```
-
-6. Commit your changes with a descriptive message following [Conventional Commits](https://www.conventionalcommits.org/):
-   ```sh
-   git commit -m "feat: add new counter increment limit"
-   ```
-
-### Commit Message Format
-
-We use conventional commit messages with gitmoji:
-
-- `✨ feat:` - New features
-- `🐛 fix:` - Bug fixes
-- `📝 docs:` - Documentation changes
-- `🎨 style:` - Code style/formatting changes
-- `♻️ refactor:` - Code refactoring
-- `✅ test:` - Test additions or updates
-- `🔧 chore:` - Build process or auxiliary tool changes
-- `⚡️ perf:` - Performance improvements
-- `👷 ci:` - CI/CD changes
-
-## Coding Standards
-
-### TypeScript
-
-- Use **strict mode** TypeScript
-- Enable all recommended checks
-- Avoid `any` types - use proper typing
-- Use `const` over `let` where possible
-
-### Code Style
-
-We use **Biome** for linting and formatting:
-
-- **Indentation**: Tabs (not spaces)
-- **Quotes**: Double quotes for strings
-- **Line length**: 100 characters (recommended)
-- **Semicolons**: Required
-
-Run the following before committing:
-
-```sh
-# Check for issues
-bun run check
-
-# Auto-fix issues
-bun run check:fix
-```
-
-### File Organization
-
-- **Component source**: `src/component/`
-- **Tests**: `test/component/` (separate from source to avoid bundling)
-- **React hooks**: `src/react/`
-- **Client utilities**: `src/client/`
-- **Example app**: `example/`
-
-### Naming Conventions
-
-- **Files**: camelCase for source files, kebab-case for config files
-- **Functions**: camelCase
-- **Components**: PascalCase (React)
-- **Constants**: UPPER_SNAKE_CASE
-- **Types/Interfaces**: PascalCase
-
-## Testing
-
-### Writing Tests
-
-Place all test files in `test/component/` directory:
-
-```typescript
-import { test, expect } from "bun:test";
-import { api } from "../../src/component/_generated/api";
-import { convexTest } from "./setup.test";
-
-test("my query works", async () => {
-	const t = convexTest();
-	const result = await t.query(api.lib.myQuery, { arg: "value" });
-	expect(result).toBe("expected");
-});
-```
-
-### Running Tests
-
-```sh
-# Run all tests
-bun test
-
-# Watch mode
-bun test --watch
-
-# With coverage
-bun test --coverage
-
-# Filter by name
-bun test -t "pattern"
-
-# Stop on first failure
-bun test --bail
-```
-
-### Testing Authenticated Scenarios
-
-```typescript
-test("authenticated query", async () => {
-	const t = convexTest();
-	const asUser = t.withIdentity({ subject: "user123" });
-	const result = await asUser.query(api.lib.userQuery, {});
-	expect(result).toBeDefined();
-});
-```
-
-## Submitting Changes
-
-### Pull Request Process
-
-1. Ensure all tests pass: `bun test`
-2. Ensure linting passes: `bun run check`
-3. Ensure TypeScript compiles: `bun run typecheck`
-4. Ensure package exports are correct: `bun run attw`
-5. Update documentation if needed
-6. Push your branch to your fork
-7. Open a Pull Request against the `main` branch
-8. Fill out the PR template with:
-   - Description of changes
-   - Related issue numbers
-   - Testing performed
-   - Breaking changes (if any)
-
-### PR Review Process
-
-- At least one maintainer approval is required
-- All CI checks must pass
-- Code must follow the project's coding standards
-- Tests must be included for new features
-
-### What Happens After Your PR is Merged
-
-- Your changes will be included in the next release
-- The CHANGELOG will be updated
-- You'll be credited as a contributor
-
-## Release Process
-
-This section is for maintainers.
-
-### Version Bumping
-
-The project uses npm version scripts:
-
-```sh
-# Alpha release (pre-release)
-bun run alpha
-
-# Patch release (0.1.0 -> 0.1.1)
-bun run release
-
-# Manual version bump
-npm version [major|minor|patch]
-```
-
-### What Happens During Release
-
-1. `preversion`: Runs tests, linting, typecheck, and package validation
-2. `version`: Updates version, opens CHANGELOG.md for editing, formats it
-3. `postversion`: Pushes changes and tags to GitHub
-
-### Publishing
-
-Publishing happens automatically after version bump:
-
-```sh
-# For alpha releases
-npm publish --tag alpha
-
-# For stable releases
-npm publish
-```
-
-## Questions?
-
-If you have questions, please:
-
-- Check existing issues and discussions
-- Open a new issue for bugs
-- Start a discussion for questions
-
-Thank you for contributing!

package/prds/ENV_SETUP.md

@@ -1,222 +0,0 @@
-# Environment Variable Setup
-
-The Loops component requires a Loops.so API key to be configured. **For security, the API key should ONLY be stored in Convex environment variables.**
-
-## Setting Up the API Key
-
-### 1. Get Your Loops API Key
-
-1. Log in to your [Loops.so dashboard](https://app.loops.so)
-2. Navigate to Settings → API Keys
-3. Copy your API key
-
-### 2. Set Environment Variable in Convex
-
-**Via Convex Dashboard:**
-
-1. Go to your Convex project dashboard
-2. Navigate to **Settings** → **Environment Variables**
-3. Click **Add Variable**
-4. Set:
-   - **Name:** `LOOPS_API_KEY`
-   - **Value:** Your Loops API key
-5. Click **Save**
-
-**Via Convex CLI:**
-
-```bash
-npx convex env set LOOPS_API_KEY "your-api-key-here"
-```
-
-**Important:** The API key will be automatically available as `process.env.LOOPS_API_KEY` in your Convex functions.
-
-### 3. Initialize the Component
-
-Once the environment variable is set, initialize the component in your app:
-
-```typescript
-// In your app's convex/loops.ts (or similar)
-import { Loops } from "robertalv/loops-component";
-import { components } from "./_generated/api";
-
-/**
- * Initialize Loops client.
- * The API key is automatically loaded from process.env.LOOPS_API_KEY
- */
-const loops = new Loops(components.loopsComponent);
-
-export const {
-  addContact,
-  sendTransactional,
-  // ... other functions
-} = loops.api();
-```
-
-## Security Best Practices
-
-### ✅ DO:
-
-1. **Store API key in Convex environment variables only**
-   ```typescript
-   // ✅ GOOD - Uses environment variable automatically
-   const loops = new Loops(components.loopsComponent);
-   ```
-
-2. **Use different keys for different environments**
-   - Development: Set `LOOPS_API_KEY` in your dev deployment
-   - Production: Set `LOOPS_API_KEY` in your prod deployment
-   - Each deployment has its own environment variables
-
-3. **Rotate API keys regularly**
-   - Generate new keys in Loops dashboard
-   - Update environment variable
-   - Remove old keys
-
-4. **Restrict API key access**
-   - Only give access to necessary team members
-   - Use Convex's role-based access control for dashboard access
-
-### ❌ DON'T:
-
-1. **Don't hardcode API keys in code**
-   ```typescript
-   // ❌ BAD - Never do this!
-   const loops = new Loops(components.loopsComponent, {
-     apiKey: "sk-abc123..." // NEVER hardcode!
-   });
-   ```
-
-2. **Don't commit API keys to git**
-   ```typescript
-   // ❌ BAD - API key in code = exposed in git history
-   const API_KEY = "sk-abc123...";
-   ```
-
-3. **Don't pass API keys from client-side code**
-   ```typescript
-   // ❌ BAD - Never accept API keys from clients
-   export const sendEmail = action({
-     args: {
-       apiKey: v.string(), // NEVER accept API key as argument!
-       email: v.string(),
-     },
-     // ...
-   });
-   ```
-
-4. **Don't log API keys**
-   ```typescript
-   // ❌ BAD - Never log API keys
-   console.log("API Key:", process.env.LOOPS_API_KEY);
-   ```
-
-5. **Don't store in client-side code or config files**
-   - Not in `.env.local` (if exposed to client)
-   - Not in React components
-   - Not in browser storage
-
-## Environment Variable Management
-
-### Viewing Environment Variables
-
-```bash
-# List all environment variables
-npx convex env list
-
-# View a specific variable (value is masked for security)
-npx convex env get LOOPS_API_KEY
-```
-
-### Updating Environment Variables
-
-```bash
-# Update existing variable
-npx convex env set LOOPS_API_KEY "new-api-key-here"
-```
-
-### Removing Environment Variables
-
-```bash
-# Remove a variable
-npx convex env remove LOOPS_API_KEY
-```
-
-## Multiple Environments
-
-If you have multiple Convex deployments (dev, staging, prod), set the environment variable in each:
-
-```bash
-# Development deployment
-npx convex env set LOOPS_API_KEY "dev-key-here" --prod=false
-
-# Production deployment
-npx convex env set LOOPS_API_KEY "prod-key-here" --prod=true
-```
-
-## Verification
-
-To verify your API key is set correctly:
-
-```typescript
-// In a test query or action
-export const testLoopsConnection = query({
-  handler: async (ctx) => {
-    const apiKey = process.env.LOOPS_API_KEY;
-    if (!apiKey) {
-      return { error: "LOOPS_API_KEY not set in environment variables" };
-    }
-    
-    // Try a simple operation
-    const loops = new Loops(components.loopsComponent);
-    // If initialization succeeds, API key is valid
-    return { success: true, message: "Loops client initialized successfully" };
-  },
-});
-```
-
-## Troubleshooting
-
-### "Loops API key is required" Error
-
-This means `LOOPS_API_KEY` is not set in your Convex environment variables:
-
-1. Check if variable exists: `npx convex env list`
-2. Set the variable: `npx convex env set LOOPS_API_KEY "your-key"`
-3. Restart your Convex dev server if running locally
-
-### API Key Not Working
-
-1. Verify the key is correct in Loops dashboard
-2. Check if the key has expired or been rotated
-3. Ensure you're using the correct deployment's environment variables
-4. Check Convex dashboard for any environment variable errors
-
-### Testing Without Environment Variable
-
-For testing purposes only, you can pass the API key directly (but never commit this):
-
-```typescript
-// ⚠️ TESTING ONLY - Remove before production
-const loops = new Loops(components.loopsComponent, {
-  apiKey: process.env.TEST_LOOPS_API_KEY || "test-key",
-});
-```
-
-**Important:** This should only be used for local testing. In production, always use environment variables.
-
-## Security Checklist
-
-- [ ] API key stored only in Convex environment variables
-- [ ] API key NOT in source code
-- [ ] API key NOT in git repository
-- [ ] API key NOT in client-side code
-- [ ] Different keys for dev/staging/prod environments
-- [ ] API key access restricted to necessary team members
-- [ ] Regular key rotation schedule in place
-
-## Additional Resources
-
-- [Convex Environment Variables Documentation](https://docs.convex.dev/production/environment-variables)
-- [Loops.so API Documentation](https://loops.so/docs)
-- [Component Security Guide](./SECURITY.md)
-