🚀 API Deployment (Cloudflare Workers)

Unified Contract API auf Cloudflare Workers

🔐 Security Setup erforderlich

Vor API Deployment: Cloudflare Access konfigurieren!

Staging Environment MUSS geschützt sein:

api-staging.g100.dev → Cloudflare Access Policy
NDA Team Members only
One-Time PIN Authentication
24h Session Duration für Developers

📋 Übersicht

MkDocs (Static)     → Cloudflare Pages
API (Dynamic)       → Cloudflare Workers
Database            → Cloudflare D1
Cache               → Cloudflare KV
Files/Images        → Cloudflare R2 (optional)

🏗️ Projekt-Struktur

contractplattform-api/
├── wrangler.toml              ← Cloudflare Config
├── package.json
├── tsconfig.json
├── .env.example               ← Lokale Development
├── .gitignore
│
├── src/
│   ├── index.ts               ← Main Worker Entry
│   ├── router.ts              ← Hono Router
│   │
│   ├── routes/
│   │   ├── contracts.ts       ← POST /v1/contracts
│   │   ├── auth.ts            ← POST /v1/auth/login
│   │   ├── webhooks.ts        ← POST /webhooks/*
│   │   └── health.ts          ← GET /health
│   │
│   ├── services/
│   │   ├── adobe.ts           ← Adobe Express Integration
│   │   ├── microsoft.ts       ← MS Graph Integration
│   │   ├── salesforce.ts      ← Salesforce Integration
│   │   ├── sevdesk.ts         ← sevDesk Integration
│   │   ├── stripe.ts          ← Stripe Integration
│   │   └── blockchain.ts      ← Polygon/NFT Integration
│   │
│   ├── db/
│   │   ├── schema.sql         ← D1 Schema
│   │   └── queries.ts         ← SQL Queries
│   │
│   └── types/
│       ├── contract.ts
│       ├── user.ts
│       └── env.ts             ← Environment Types
│
└── migrations/
    ├── 0001_init.sql
    └── 0002_add_nft_fields.sql

📄 wrangler.toml Template

name = "contractplattform-api"
main = "src/index.ts"
compatibility_date = "2024-01-15"

# Account ID (deine Cloudflare Account ID)
account_id = "edeaf72f08c3145711f257893d9ddab1"

# Workers AI (optional - für AI Features)
# [ai]
# binding = "AI"

# D1 Database
[[d1_databases]]
binding = "DB"
database_name = "contractplattform-prod"
database_id = "" # ← Wird nach 'wrangler d1 create' ausgefüllt

# KV Namespace (Cache)
[[kv_namespaces]]
binding = "CACHE"
id = "" # ← Wird nach 'wrangler kv:namespace create' ausgefüllt

# R2 Bucket (File Storage - optional)
# [[r2_buckets]]
# binding = "FILES"
# bucket_name = "contractplattform-files"

# Durable Objects (Sessions - optional)
# [[durable_objects.bindings]]
# name = "SESSIONS"
# class_name = "SessionStore"

# Environment Variables (PUBLIC - nicht sensitiv)
[vars]
ENVIRONMENT = "production"
API_VERSION = "v1"
INSTANCE_ID = "master"

# Secrets werden NICHT hier gespeichert!
# Verwende: wrangler secret put SECRET_NAME
# Oder: Cloudflare Dashboard → Workers → Settings → Variables

# ---
# Preview Environment (für Branches)
# ---
[env.preview]
name = "contractplattform-api-preview"

[[env.preview.d1_databases]]
binding = "DB"
database_name = "contractplattform-preview"
database_id = "" # ← Separate Preview DB

[[env.preview.kv_namespaces]]
binding = "CACHE"
id = "" # ← Separate Preview KV

[env.preview.vars]
ENVIRONMENT = "preview"

# ---
# Development Environment (lokal)
# ---
[env.dev]
name = "contractplattform-api-dev"

[[env.dev.d1_databases]]
binding = "DB"
database_name = "contractplattform-dev"
database_id = "" # ← Lokale DB

[[env.dev.kv_namespaces]]
binding = "CACHE"
id = "" # ← Dev KV

[env.dev.vars]
ENVIRONMENT = "development"

🚀 Setup Guide

1. Cloudflare Account vorbereiten

# Wrangler CLI installieren
npm install -g wrangler

# Login
wrangler login

# Account ID verifizieren
wrangler whoami
# ✅ Account ID: edeaf72f08c3145711f257893d9ddab1

2. D1 Database erstellen

# Production Database
wrangler d1 create contractplattform-prod

# Output kopieren:
# ✅ Successfully created DB 'contractplattform-prod'
# [[d1_databases]]
# binding = "DB"
# database_name = "contractplattform-prod"
# database_id = "abc123-def456-ghi789"

# Preview Database
wrangler d1 create contractplattform-preview

# Dev Database (lokal)
wrangler d1 create contractplattform-dev

Database IDs in wrangler.toml eintragen!

3. KV Namespace erstellen

# Production KV
wrangler kv:namespace create CACHE

# Output kopieren:
# ✅ Successfully created KV namespace
# [[kv_namespaces]]
# binding = "CACHE"
# id = "xyz123abc456"

# Preview KV
wrangler kv:namespace create CACHE --preview

# Dev KV
wrangler kv:namespace create CACHE --env dev

Namespace IDs in wrangler.toml eintragen!

4. Database Schema anwenden

# Production
wrangler d1 migrations apply contractplattform-prod --remote

# Preview
wrangler d1 migrations apply contractplattform-preview --remote

# Dev (lokal)
wrangler d1 migrations apply contractplattform-dev --local

5. Secrets hinzufügen

Option A: Via CLI

# Adobe
wrangler secret put ADOBE_CLIENT_ID
wrangler secret put ADOBE_CLIENT_SECRET
wrangler secret put ADOBE_API_KEY

# Microsoft
wrangler secret put MS_CLIENT_ID
wrangler secret put MS_CLIENT_SECRET
wrangler secret put MS_TENANT_ID

# Salesforce
wrangler secret put SALESFORCE_CLIENT_ID
wrangler secret put SALESFORCE_CLIENT_SECRET
wrangler secret put SALESFORCE_USERNAME
wrangler secret put SALESFORCE_PASSWORD
wrangler secret put SALESFORCE_SECURITY_TOKEN

# sevDesk
wrangler secret put SEVDESK_API_TOKEN

# Stripe
wrangler secret put STRIPE_SECRET_KEY
wrangler secret put STRIPE_WEBHOOK_SECRET

# Blockchain
wrangler secret put POLYGON_RPC_URL
wrangler secret put POLYGON_PRIVATE_KEY

# IPFS
wrangler secret put PINATA_API_KEY
wrangler secret put PINATA_SECRET_KEY

# JWT
wrangler secret put JWT_SECRET

# Plane.so
wrangler secret put PLANE_API_KEY

Option B: Via Dashboard (empfohlen!)

https://dash.cloudflare.com/edeaf72f08c3145711f257893d9ddab1/workers
Workers → contractplattform-api → Settings → Variables
Add Variable → Select "Encrypt" → Save

📝 TypeScript Environment Types

// src/types/env.ts

export interface Env {
  // Bindings
  DB: D1Database;
  CACHE: KVNamespace;
  // FILES: R2Bucket; // optional

  // Public Variables
  ENVIRONMENT: 'production' | 'preview' | 'development';
  API_VERSION: string;
  INSTANCE_ID: string;

  // Secrets (encrypted)
  ADOBE_CLIENT_ID: string;
  ADOBE_CLIENT_SECRET: string;
  ADOBE_API_KEY: string;

  MS_CLIENT_ID: string;
  MS_CLIENT_SECRET: string;
  MS_TENANT_ID: string;

  SALESFORCE_CLIENT_ID: string;
  SALESFORCE_CLIENT_SECRET: string;
  SALESFORCE_USERNAME: string;
  SALESFORCE_PASSWORD: string;
  SALESFORCE_SECURITY_TOKEN: string;

  SEVDESK_API_TOKEN: string;

  STRIPE_SECRET_KEY: string;
  STRIPE_WEBHOOK_SECRET: string;

  POLYGON_RPC_URL: string;
  POLYGON_PRIVATE_KEY: string;

  PINATA_API_KEY: string;
  PINATA_SECRET_KEY: string;

  JWT_SECRET: string;

  PLANE_API_KEY: string;
}

🧪 Lokale Development

.env für lokale Tests

# .env (im Root-Verzeichnis)

# Adobe
ADOBE_CLIENT_ID=your_dev_client_id
ADOBE_CLIENT_SECRET=your_dev_secret
ADOBE_API_KEY=your_dev_api_key

# Microsoft
MS_CLIENT_ID=your_dev_client_id
MS_CLIENT_SECRET=your_dev_secret
MS_TENANT_ID=your_dev_tenant_id

# Salesforce
SALESFORCE_CLIENT_ID=your_dev_consumer_key
SALESFORCE_CLIENT_SECRET=your_dev_consumer_secret
SALESFORCE_USERNAME=dev@example.com
SALESFORCE_PASSWORD=your_dev_password
SALESFORCE_SECURITY_TOKEN=your_dev_token

# sevDesk
SEVDESK_API_TOKEN=your_dev_token

# Stripe (TEST KEYS!)
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_test_...

# Polygon (TESTNET!)
POLYGON_RPC_URL=https://polygon-mumbai.g.alchemy.com/v2/YOUR_KEY
POLYGON_PRIVATE_KEY=0xYOUR_TESTNET_PRIVATE_KEY

# IPFS
PINATA_API_KEY=your_dev_key
PINATA_SECRET_KEY=your_dev_secret

# JWT
JWT_SECRET=dev_secret_min_32_chars_long

# Plane.so
PLANE_API_KEY=your_dev_token

Dev Server starten

# Install dependencies
npm install

# Start dev server (with .env)
npm run dev

# Or with wrangler
wrangler dev --local --persist

Dev Server läuft auf: http://localhost:8787

🚀 Deployment

Deploy to Production

# Build & Deploy
wrangler deploy

# Output:
# ✅ Uploaded contractplattform-api
# ✅ Published contractplattform-api
# 🌍 https://contractplattform-api.YOUR_SUBDOMAIN.workers.dev

Deploy to Preview

wrangler deploy --env preview

# Output:
# ✅ Published contractplattform-api-preview
# 🌍 https://contractplattform-api-preview.YOUR_SUBDOMAIN.workers.dev

Custom Domain

# Via CLI
wrangler routes add "api.contractplattform.dev/*" contractplattform-api

# Oder im Dashboard:
# Workers → contractplattform-api → Triggers → Custom Domains
# Add: api.contractplattform.dev

DNS wird automatisch konfiguriert!

📊 Monitoring

Cloudflare Dashboard

Analytics:

Workers → contractplattform-api → Analytics

Requests/Minute
Error Rate
CPU Time
Success Rate

Logs (Tail):

wrangler tail

# Or in Dashboard:
Workers → contractplattform-api → Logs → Begin log stream

Logpush (für Production):
Workers → Logpush
Export zu: S3, R2, Datadog, etc.

🔍 Testing

Health Check

curl https://api.contractplattform.dev/health

# Response:
{
  "status": "ok",
  "version": "v1",
  "environment": "production",
  "timestamp": "2026-01-15T15:30:00Z"
}

Contract API Test

curl -X POST https://api.contractplattform.dev/v1/contracts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "morelo",
    "type": "kfz_kaufvertrag",
    "party_a": { ... },
    "party_b": { ... },
    "asset": { ... },
    "financials": { ... }
  }'

✅ Deployment Checklist

Pre-Deployment

[ ] wrangler.toml konfiguriert
[ ] D1 Database erstellt
[ ] KV Namespace erstellt
[ ] Secrets hinzugefügt
[ ] Migrations angewendet
[ ] Lokale Tests erfolgreich

Deployment

[ ] wrangler deploy erfolgreich
[ ] Custom Domain konfiguriert
[ ] SSL Zertifikat aktiv
[ ] Health Check OK

Post-Deployment

[ ] API Endpoints testen
[ ] Monitoring aktiviert
[ ] Error Tracking (Sentry) konfiguriert
[ ] Logs überprüfen

📞 Support URLs

Resource	URL
Cloudflare Dashboard	https://dash.cloudflare.com/edeaf72f08c3145711f257893d9ddab1
Workers & Pages	https://dash.cloudflare.com/edeaf72f08c3145711f257893d9ddab1/workers
D1 Databases	https://dash.cloudflare.com/edeaf72f08c3145711f257893d9ddab1/d1
Wrangler Docs	https://developers.cloudflare.com/workers/wrangler/
D1 Docs	https://developers.cloudflare.com/d1/

Next: Secrets Configuration →