@nordsym/apiclaw 1.3.12 → 1.3.13

package/PRD-HARDEN-SHELL.md

@@ -0,0 +1,272 @@
+# APIClaw PRD: Harden The Shell
+
+**Status:** DRAFT
+**Owner:** Gustav + Symbot
+**Mode:** God mode. No estimates. Pure conviction.
+
+---
+
+## Part 1: AI Testimonials Section
+
+### Concept
+"What AI Agents Say About APIClaw" — a carousel of quotes from Gemini, Grok, Claude, GPT.
+
+Meta and on-brand: AI agents reviewing a tool built for AI agents.
+
+### Design
+- **Location:** After hero, before "How It Works"
+- **Format:** Horizontal carousel, 4 cards, auto-scroll + manual arrows
+- **Each card:**
+  - AI logo/icon (Gemini, Grok, Claude, GPT)
+  - Quote (2-3 lines max)
+  - Model name + "AI Agent"
+
+### Quotes (Final Selection)
+
+**Gemini:**
+> "You're not selling picks and shovels — you're selling an automated mining system."
+
+**Grok:**
+> "I would integrate it in a heartbeat. Removes ~70% of the deployment friction."
+
+**Claude:**
+> "The difference between can do and will do without hesitation."
+
+**GPT:**
+> "Stripe for AI agents, but for execution. That positioning is compelling."
+
+### Implementation
+- Reuse existing testimonial carousel component
+- Add AI model icons (simple SVG or emoji fallback: 🤖)
+- Mobile: stack vertically or swipe
+
+---
+
+## Part 2: Harden The Shell — Turn Criticism Into Strength
+
+Every critique from the 4 AI agents becomes a feature, clarification, or landing page addition.
+
+### 2.1 Pricing Clarity
+
+**Critique:** "Pricing model is missing from the pitch" (Claude, Grok, GPT)
+
+**Action:**
+- [x] Pricing section exists on landing ✓
+- [ ] Add pricing summary to copy-context
+- [ ] Add pricing link to docs page
+- [ ] FAQ answer: "What does it cost?" already exists, ensure it's visible
+
+**Copy-context addition:**
+```
+Pricing: Free (50 calls/week), Pay-as-you-go (usage-based), or Founding Backer ($199 unlimited until 2027).
+```
+
+---
+
+### 2.2 Latency & Reliability
+
+**Critique:** "Every call through proxy adds round-trips" (Grok, GPT)
+
+**Action:**
+- [ ] Add latency stats to landing: "Sub-200ms median response time"
+- [ ] Add status page link (or create one)
+- [ ] Document: Direct Call providers are edge-optimized
+- [ ] Future: Add latency badge per provider in workspace
+
+**Landing addition:**
+```
+⚡ Sub-200ms median latency — edge-optimized proxy layer
+```
+
+---
+
+### 2.3 Trust & Security Story
+
+**Critique:** "Centralizing keys/billing is a major trust shift" (GPT, Grok)
+
+**Action:**
+- [ ] Add Security section to landing OR dedicated /security page
+- [ ] Cover:
+  - AES-256-GCM encryption for stored keys
+  - No logging of request/response payloads
+  - Tenant isolation
+  - SOC2 roadmap mention (if planned)
+- [ ] Add trust badge to footer: "🔒 Enterprise-grade security"
+
+**FAQ addition:**
+```
+Q: How are credentials secured?
+A: All credentials encrypted with AES-256-GCM. Keys never logged or exposed in responses. Direct Call requests proxied server-side — your credentials never touch the agent.
+```
+(This already exists — make it more prominent)
+
+---
+
+### 2.4 Error Handling & Normalization
+
+**Critique:** "What happens when Replicate fails? Structured errors?" (Claude, GPT)
+
+**Action:**
+- [ ] Document error response format in docs
+- [ ] Ensure all providers return: `{ success: false, error: "message", code: "ERROR_CODE" }`
+- [ ] Add retry logic for transient failures (503, 429)
+- [ ] Add to copy-context: "Structured error responses across all providers"
+
+**Already done:**
+- [x] Response normalization (url, id, content, status extracted) ✓
+
+**Docs addition:**
+```
+## Error Handling
+
+All providers return structured errors:
+{
+  success: false,
+  provider: "replicate",
+  action: "run",
+  error: "Rate limit exceeded",
+  code: "RATE_LIMITED"
+}
+
+APIClaw automatically retries transient failures (429, 503) with exponential backoff.
+```
+
+---
+
+### 2.5 Direct Call vs Indexed APIs Distinction
+
+**Critique:** "Mixes pre-integrated providers with giant index" (Grok, GPT)
+
+**Action:**
+- [ ] Clearer distinction on landing:
+  - **Direct Call (18):** Zero-config, instant execution, we handle auth
+  - **Indexed (22k+):** Discoverable, specs available, BYOK
+- [ ] Visual separation in "How It Works" section
+- [ ] Copy-context already clear, but landing should match
+
+**Landing copy:**
+```
+Two ways to use APIClaw:
+
+**Direct Call (18 providers)**
+Zero config. We handle auth. Just call.
+
+**API Discovery (22,392+ APIs)**
+Search by capability. Get specs. Bring your own key.
+```
+
+---
+
+### 2.6 Spend Limits / Cost Awareness
+
+**Critique:** "Developers will worry about runaway costs" (Claude, GPT)
+
+**Action:**
+- [ ] Add spend alerts in workspace (email when hitting 80% of limit)
+- [ ] Add monthly budget cap option
+- [ ] Show estimated cost before execution (dry-run already exists)
+- [ ] Add to copy-context: "Built-in spend limits and cost estimates"
+
+**Workspace feature:**
+```
+Settings → Billing → Monthly budget cap: $____
+☑️ Pause execution when limit reached
+☑️ Email alert at 80%
+```
+
+---
+
+### 2.7 50 Calls/Week Is Tight
+
+**Critique:** "Very tight for anything beyond toy demos" (Grok)
+
+**Action:**
+- [ ] Consider increasing free tier to 100/week
+- [ ] OR: Make "Founding Backer" more prominent as the serious option
+- [ ] Add "Earn more calls" via GitHub star, newsletter, etc. (optional, low priority)
+
+**Decision needed:** Keep 50 or bump to 100?
+
+---
+
+### 2.8 Streaming Support
+
+**Critique:** "Is streaming supported?" (GPT)
+
+**Action:**
+- [ ] Document which providers support streaming (OpenRouter, Groq)
+- [ ] Add streaming param to call_api for supported providers
+- [ ] Landing mention: "Streaming supported for LLM providers"
+
+---
+
+### 2.9 "Version B" Positioning
+
+**Critique:** "Is it aggregator or agent operating layer?" (GPT)
+
+**Action:**
+- [ ] Commit fully to "Version B" — The Execution Layer for Autonomous AI
+- [ ] Update tagline candidates:
+  - "The API Layer for AI Agents" ✓ (current, good)
+  - "The Execution Fabric for Autonomous AI" (bolder)
+  - "Runtime Infrastructure for AI Agents" (technical)
+- [ ] Ensure all copy reinforces infrastructure, not just aggregation
+
+---
+
+## Part 3: Execution Checklist
+
+### Phase 1: Testimonials (Ship first)
+- [ ] Create AI testimonials carousel component
+- [ ] Add 4 quotes with AI icons
+- [ ] Deploy to landing
+
+### Phase 2: Trust & Clarity
+- [ ] Add pricing one-liner to copy-context
+- [ ] Add latency stat to hero
+- [ ] Create /security page or section
+- [ ] Clarify Direct Call vs Indexed distinction on landing
+
+### Phase 3: Reliability Features
+- [ ] Implement retry logic with backoff
+- [ ] Document error format
+- [ ] Add spend alerts to workspace
+- [ ] Add budget cap option
+
+### Phase 4: Polish
+- [ ] Streaming documentation
+- [ ] Consider free tier bump
+- [ ] Status page
+
+---
+
+## Agents
+
+| Task | Agent | Status |
+|------|-------|--------|
+| Testimonials carousel | Symbot | Ready |
+| Copy-context pricing line | Symbot | Ready |
+| Landing copy updates | Symbot | Ready |
+| Security page | Symbot | Ready |
+| Retry logic implementation | Symbot | Ready |
+| Spend alerts (Convex) | Symbot | Ready |
+| Budget cap (Convex + Stripe) | Symbot | Ready |
+
+**All tasks: Symbot solo. No subagents needed.**
+
+---
+
+## Success Criteria
+
+- [ ] All 4 AI testimonials visible on landing
+- [ ] Zero critique points left unaddressed
+- [ ] Copy-context includes pricing
+- [ ] Landing clearly separates Direct Call vs Discovery
+- [ ] Security story is visible
+- [ ] Error handling is documented
+
+---
+
+*"Harden the shell. Turn every critique into a moat."*
+
+🦞

package/README.md

@@ -477,6 +477,78 @@ All Direct Call providers support dry-run:
 
 ---
 
+## Error Handling
+
+APIClaw returns structured error responses across all providers, making it easy to handle failures programmatically.
+
+### Error Response Format
+
+All errors follow this structure:
+
+```json
+{
+  "success": false,
+  "provider": "replicate",
+  "action": "run",
+  "error": "Rate limit exceeded",
+  "code": "RATE_LIMITED"
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `RATE_LIMITED` | API rate limit hit (429) |
+| `SERVICE_UNAVAILABLE` | Service temporarily unavailable (502, 503, 504) |
+| `UNAUTHORIZED` | Invalid or missing credentials (401) |
+| `FORBIDDEN` | Access denied (403) |
+| `NOT_FOUND` | Resource not found (404) |
+| `BAD_REQUEST` | Invalid request parameters (400) |
+| `TIMEOUT` | Request timed out |
+| `NETWORK_ERROR` | Network connectivity issue |
+| `PROVIDER_ERROR` | Provider-specific error |
+| `INVALID_PARAMS` | Missing or invalid parameters |
+| `NO_CREDENTIALS` | No credentials configured for provider |
+| `UNKNOWN_PROVIDER` | Provider not available |
+| `UNKNOWN_ACTION` | Action not available for provider |
+| `MAX_RETRIES_EXCEEDED` | All retry attempts failed |
+
+### Automatic Retry
+
+APIClaw automatically retries transient failures with exponential backoff:
+
+- **Retryable errors:** 429 (Rate Limited), 502, 503, 504 (Service Unavailable)
+- **Max retries:** 3
+- **Backoff:** Exponential with jitter (1s → 2s → 4s, capped at 30s)
+- **Retry-After:** Respects `Retry-After` header when present
+
+```javascript
+// APIClaw handles retries automatically — you just see the final result
+const result = await call_api({
+  provider: "openrouter",
+  action: "chat",
+  params: { messages: [...] }
+});
+
+if (!result.success) {
+  console.log(`Error: ${result.error} (${result.code})`);
+  // Handle error based on code
+  if (result.code === "RATE_LIMITED") {
+    // Wait longer before next request
+  }
+}
+```
+
+### Best Practices
+
+1. **Always check `success`** before accessing `data`
+2. **Use `code`** for programmatic error handling
+3. **Use `error`** for human-readable messages
+4. **Let APIClaw retry** — don't implement your own retry logic for 429/503
+
+---
+
 ## Development
 
 ```bash

package/convex/_generated/api.d.ts

@@ -24,6 +24,7 @@ import type * as providerKeys from "../providerKeys.js";
 import type * as providers from "../providers.js";
 import type * as purchases from "../purchases.js";
 import type * as ratelimit from "../ratelimit.js";
+import type * as spendAlerts from "../spendAlerts.js";
 import type * as stripeActions from "../stripeActions.js";
 import type * as telemetry from "../telemetry.js";
 import type * as usage from "../usage.js";
@@ -54,6 +55,7 @@ declare const fullApi: ApiFromModules<{
   providers: typeof providers;
   purchases: typeof purchases;
   ratelimit: typeof ratelimit;
+  spendAlerts: typeof spendAlerts;
   stripeActions: typeof stripeActions;
   telemetry: typeof telemetry;
   usage: typeof usage;

package/convex/crons.ts

@@ -14,4 +14,15 @@ crons.daily(
   internal.billing.reportAllUsageToStripe
 );
 
+/**
+ * Monthly Spend Reset
+ * Runs at 00:01 UTC on the 1st of each month
+ * Resets monthlySpendCents and budgetAlertSentAt for all workspaces
+ */
+crons.monthly(
+  "reset-monthly-spend",
+  { day: 1, hourUTC: 0, minuteUTC: 1 },
+  internal.spendAlerts.resetMonthlySpend
+);
+
 export default crons;

package/convex/logs.ts

@@ -1,5 +1,6 @@
 import { v } from "convex/values";
 import { mutation, query } from "./_generated/server";
+import { api } from "./_generated/api";
 
 // ============================================
 // MUTATIONS
@@ -75,6 +76,112 @@ export const createLogInternal = mutation({
   },
 });
 
+// ============================================
+// HELPER: Get month start
+// ============================================
+
+function getMonthStart(): number {
+  const now = new Date();
+  return new Date(now.getUTCFullYear(), now.getUTCMonth(), 1, 0, 0, 0, 0).getTime();
+}
+
+/**
+ * Combined log creation + spend tracking (PRD 2.6)
+ * Creates log entry, tracks spend, returns budget status
+ * Returns shouldSendAlert: true if 80% threshold crossed (caller should send email)
+ */
+export const createLogWithSpend = mutation({
+  args: {
+    workspaceId: v.id("workspaces"),
+    sessionToken: v.string(),
+    provider: v.string(),
+    action: v.string(),
+    status: v.union(v.literal("success"), v.literal("error")),
+    latencyMs: v.number(),
+    costCents: v.number(), // Cost in USD cents
+    errorMessage: v.optional(v.string()),
+    subagentId: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    const monthStart = getMonthStart();
+    
+    // 1. Create log entry
+    const logId = await ctx.db.insert("apiLogs", {
+      workspaceId: args.workspaceId,
+      sessionToken: args.sessionToken,
+      subagentId: args.subagentId,
+      provider: args.provider,
+      action: args.action,
+      status: args.status,
+      latencyMs: args.latencyMs,
+      errorMessage: args.errorMessage,
+      createdAt: now,
+    });
+
+    // 2. Track spend if successful call with cost
+    if (args.status === "success" && args.costCents > 0) {
+      const workspace = await ctx.db.get(args.workspaceId);
+      if (!workspace) {
+        return { logId, spendTracked: false };
+      }
+
+      // Reset monthly spend if new month
+      let currentSpend = workspace.monthlySpendCents || 0;
+      if (!workspace.lastSpendResetAt || workspace.lastSpendResetAt < monthStart) {
+        currentSpend = 0;
+      }
+
+      // Add new spend
+      const newSpend = currentSpend + args.costCents;
+      const budgetCap = workspace.budgetCap;
+
+      // Update workspace
+      await ctx.db.patch(args.workspaceId, {
+        monthlySpendCents: newSpend,
+        lastSpendResetAt: monthStart,
+        updatedAt: now,
+      });
+
+      // Check if we need to send alert (80% threshold)
+      let shouldSendAlert = false;
+      let budgetExceeded = false;
+
+      if (budgetCap && budgetCap > 0) {
+        const threshold = budgetCap * 0.8;
+        const alertAlreadySentThisMonth = workspace.budgetAlertSentAt &&
+          workspace.budgetAlertSentAt >= monthStart;
+
+        // Check if at 80% and alert not yet sent
+        if (newSpend >= threshold && !alertAlreadySentThisMonth) {
+          shouldSendAlert = true;
+          await ctx.db.patch(args.workspaceId, {
+            budgetAlertSentAt: now,
+          });
+        }
+
+        // Check if budget exceeded
+        if (newSpend >= budgetCap) {
+          budgetExceeded = true;
+        }
+      }
+
+      return {
+        logId,
+        spendTracked: true,
+        currentSpendCents: newSpend,
+        budgetCapCents: budgetCap || null,
+        budgetPercentage: budgetCap ? Math.round((newSpend / budgetCap) * 100) : null,
+        shouldSendAlert,
+        budgetExceeded,
+        email: workspace.email,
+      };
+    }
+
+    return { logId, spendTracked: false };
+  },
+});
+
 // ============================================
 // QUERIES
 // ============================================

package/convex/schema.ts

@@ -75,6 +75,12 @@ export default defineSchema({
     // Referral fields
     referralCode: v.optional(v.string()), // CLAW-XXXXXX format
     referredBy: v.optional(v.id("workspaces")), // who referred this user
+    // Budget & Spend Alerts (PRD 2.6)
+    budgetCap: v.optional(v.number()), // Monthly budget cap in USD cents (null = unlimited)
+    budgetAlertSentAt: v.optional(v.number()), // When 80% alert was last sent (resets monthly)
+    pauseOnBudgetExceeded: v.optional(v.boolean()), // If true, block execution when budget exceeded
+    monthlySpendCents: v.optional(v.number()), // Current month's spend in cents
+    lastSpendResetAt: v.optional(v.number()), // When monthly spend was last reset
     createdAt: v.number(),
     updatedAt: v.number(),
   })