feat: support 95% of Hypay + add docs site

Author: YossiSaadi

.github/workflows/docs-deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for better build performance
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: npm ci
+
+      - name: Build documentation
+        working-directory: ./docs
+        run: npm run build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/build
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -18,6 +18,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version-file: .nvmrc
+          registry-url: 'https://npm.pkg.github.com'
       - name: Install dependencies
         run: npm ci
       - name: Build
@@ -28,6 +29,6 @@ jobs:
         uses: cycjimmy/semantic-release-action@v4
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GIT_AUTHOR_NAME: 'ci'
           GIT_AUTHOR_EMAIL: 'yossisaadi@gmail.com'

.gitignore

@@ -121,4 +121,7 @@ lib/
 # ESLint cache
 .eslintcache
 
-.env
+.env
+
+# NPM configuration with tokens
+.npmrc

.npmrc.example

@@ -0,0 +1,6 @@
+# Copy this file to .npmrc and replace with your actual GitHub token
+# Get token from: https://github.com/settings/tokens
+# Required scopes: read:packages, write:packages
+
+@yosolutions:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN_HERE

LICENSE

@@ -0,0 +1,190 @@
+# 🚀 Publishing Guide: Multiple Methods
+
+## 🎯 **Method 1: Semantic Release (Recommended)**
+
+Your `release.yml` workflow is now configured for GitHub Packages. Here's how to use it:
+
+### Prerequisites
+
+1. **Commit Message Format**: Use conventional commits for semantic versioning
+   ```bash
+   feat: add new payment method (creates minor version bump)
+   fix: resolve validation bug (creates patch version bump)
+   BREAKING CHANGE: remove deprecated API (creates major version bump)
+   ```
+
+### Steps to Publish
+
+1. **Make your changes and commit with proper format:**
+
+   ```bash
+   git add .
+   git commit -m "feat: add Apple Pay integration"
+   git push origin main
+   ```
+
+2. **Trigger the release workflow:**
+   - Go to GitHub → Actions tab
+   - Click "Release" workflow
+   - Click "Run workflow" button
+   - Select "main" branch and click "Run workflow"
+
+3. **What happens automatically:**
+   - ✅ Builds and tests your package
+   - ✅ Analyzes commits to determine version bump
+   - ✅ Updates package.json version
+   - ✅ Generates CHANGELOG.md
+   - ✅ Creates GitHub release
+   - ✅ Publishes to GitHub Packages
+   - ✅ Commits version changes back to repo
+
+---
+
+## ⚡ **Method 2: Manual Release**
+
+For quick releases without semantic versioning:
+
+### Steps
+
+1. **Version bump locally:**
+
+   ```bash
+   npm version patch  # 0.1.0 → 0.1.1
+   npm version minor  # 0.1.1 → 0.2.0
+   npm version major  # 0.2.0 → 1.0.0
+   ```
+
+2. **Set up authentication:**
+
+   ```bash
+   # Copy and edit the .npmrc file
+   cp .npmrc.example .npmrc
+   # Edit .npmrc and add your GitHub token
+   ```
+
+3. **Build and publish:**
+
+   ```bash
+   npm run build
+   npm test
+   npm publish
+   ```
+
+4. **Push version tags:**
+   ```bash
+   git push origin main --tags
+   ```
+
+---
+
+## 🔧 **Method 3: GitHub Actions (Simple)**
+
+Use the existing `publish.yml` workflow:
+
+1. **Create a GitHub release:**
+   - Go to GitHub → Releases
+   - Click "Create a new release"
+   - Create new tag (e.g., `v0.1.1`)
+   - Add release title and description
+   - Click "Publish release"
+
+2. **Workflow runs automatically:**
+   - Triggered by release creation
+   - Builds, tests, and publishes to GitHub Packages
+
+---
+
+## 📋 **Quick Comparison**
+
+| Method               | Best For        | Automation Level | Version Control |
+| -------------------- | --------------- | ---------------- | --------------- |
+| **Semantic Release** | Teams, CI/CD    | Fully Automated  | Commit-based    |
+| **Manual**           | Quick fixes     | Manual           | Manual          |
+| **GitHub Actions**   | Simple releases | Semi-automated   | Manual          |
+
+---
+
+## 🎯 **Recommended Workflow**
+
+### For Regular Development:
+
+```bash
+# 1. Make changes
+git add .
+git commit -m "feat: add query functionality"
+git push origin main
+
+# 2. Go to GitHub Actions → Release → Run workflow
+# 3. Done! Package automatically published
+```
+
+### For Hotfixes:
+
+```bash
+# Quick manual release
+npm version patch
+npm run build && npm publish
+git push origin main --tags
+```
+
+---
+
+## 🔍 **Verification Steps**
+
+After publishing, verify your package:
+
+1. **Check GitHub Packages:**
+   - Go to your repository
+   - Click "Packages" tab
+   - Verify new version is listed
+
+2. **Test import:**
+
+   ```typescript
+   // In your Supabase Edge Function
+   import { HypClient } from 'hyp-api';
+   console.log('Package imported successfully!');
+   ```
+
+3. **Check version:**
+   ```bash
+   # From another project
+   npm install hyp-api@latest
+   ```
+
+---
+
+## 🚨 **Troubleshooting**
+
+### "Package not found"
+
+- Check GitHub token has `write:packages` permission
+- Verify package name matches repo owner: `hyp-api`
+
+### "Authentication failed"
+
+- Ensure `.npmrc` has correct token
+- Token must have `repo` scope for private repos
+
+### "Semantic release failed"
+
+- Check commit message format
+- Ensure there are new commits since last release
+- Verify all tests pass
+
+### "Import map not working in Supabase"
+
+- ESM.sh needs time to index new packages (~5-10 minutes)
+- Try direct URL: `https://esm.sh/gh/yossisaadi/hyp-pay@0.1.1/lib/index.js`
+
+---
+
+## 🎉 **Next Steps**
+
+1. **Choose your preferred method** (I recommend Semantic Release)
+2. **Make a test change** and commit with conventional format
+3. **Run the release workflow**
+4. **Update your Supabase import map** with the new version
+5. **Test in a simple Edge Function**
+
+Your package is ready for automated publishing! 🚀