@nordsym/apiclaw 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# APIvault
+
+**Agent-native API discovery and purchasing via MCP.**
+
+> The place where AI agents discover, evaluate, and purchase API access directly. No dashboard. No manual signup. Agent-first.
+
+## What is this?
+
+APIvault is an MCP server that lets AI agents:
+1. **Discover** APIs based on capabilities ("I need to send SMS")
+2. **Evaluate** pricing, features, and success rates
+3. **Purchase** access and receive credentials instantly
+4. **Track** usage and balance
+
+## Quick Start
+
+### 1. Install dependencies
+
+```bash
+cd ~/clawd/products/api-discovery
+pnpm install
+```
+
+### 2. Build
+
+```bash
+pnpm build
+```
+
+### 3. Run tests
+
+```bash
+pnpm test
+```
+
+### 4. Add to Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "apivault": {
+      "command": "node",
+      "args": ["/Users/gustavhemmingsson/clawd/products/api-discovery/dist/index.js"]
+    }
+  }
+}
+```
+
+### 5. Run manually (stdio)
+
+```bash
+node dist/index.js
+```
+
+## MCP Tools
+
+### `discover_apis`
+
+Search for APIs by describing what you need.
+
+```
+Input:
+  query: "send SMS to Swedish numbers"
+  category?: "communication" | "search" | "ai"
+  max_results?: 5
+  region?: "SE" | "EU" | "global"
+
+Output:
+  - Ranked list of matching APIs
+  - Relevance scores
+  - Pricing info
+  - Success rates
+```
+
+### `get_api_details`
+
+Get full information about a specific API.
+
+```
+Input:
+  api_id: "46elks"
+
+Output:
+  - Full API specification
+  - All endpoints
+  - Pricing details
+  - Features and compliance
+```
+
+### `purchase_access`
+
+Purchase API access using credits.
+
+```
+Input:
+  api_id: "46elks"
+  amount_usd: 10
+
+Output:
+  - Purchase confirmation
+  - API credentials (key, username/password)
+  - Credits received
+  - Access URLs
+```
+
+### `check_balance`
+
+Check your credit balance and active purchases.
+
+```
+Input:
+  agent_id?: "your_agent_id"
+
+Output:
+  - Current balance in USD
+  - List of active purchases
+  - Total spent
+```
+
+### `add_credits`
+
+Add credits to your account (for testing).
+
+```
+Input:
+  amount_usd: 50
+
+Output:
+  - New balance
+```
+
+### `list_categories`
+
+List all available API categories.
+
+## Available APIs (MVP)
+
+| Provider | Category | Capabilities |
+|----------|----------|--------------|
+| **46elks** | communication | SMS, Voice, MMS |
+| **Resend** | communication | Email, Templates |
+| **Brave Search** | search | Web, News, Images |
+| **OpenRouter** | ai | LLM Chat, Completions |
+| **ElevenLabs** | ai | TTS, Voice Cloning |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    AI Agent                          │
+└─────────────────────┬───────────────────────────────┘
+                      │ MCP Protocol
+┌─────────────────────▼───────────────────────────────┐
+│              APIvault MCP Server                     │
+├──────────────┬──────────────┬───────────────────────┤
+│  Discovery   │   Credits    │   Purchase            │
+│  Engine      │   System     │   Handler             │
+└──────────────┴──────────────┴───────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│              API Registry (JSON)                     │
+│  • 5 APIs with full metadata                        │
+│  • Pricing, endpoints, features                     │
+└─────────────────────────────────────────────────────┘
+```
+
+## MVP Status
+
+### ✅ Working
+- [x] MCP server with 6 tools
+- [x] API discovery with keyword matching
+- [x] API registry with 5 providers
+- [x] In-memory credit system
+- [x] Mock credential generation
+- [x] Purchase flow
+
+### 🚧 Stub/Mock
+- [ ] Real API key provisioning (mock credentials)
+- [ ] Supabase persistence (in-memory)
+- [ ] Semantic search (keyword matching)
+- [ ] Real-time usage tracking
+- [ ] Webhook notifications
+
+### 🔮 Future
+- [ ] Stripe Agent Toolkit integration
+- [ ] Supabase for persistence
+- [ ] Embeddings for semantic search
+- [ ] More API providers
+- [ ] Usage webhooks
+
+## Backend (Convex)
+
+**Deployment:** `https://blessed-chicken-640.convex.cloud`
+**Dashboard:** https://dashboard.convex.dev/t/gustav-4d573/apiclaw
+
+### Schema
+
+- **users** — email, clerkId, credits (cents)
+- **purchases** — userId, apiId, credentials, status, purchasedAt, expiresAt
+- **transactions** — userId, type, amount, description, createdAt
+
+### Functions
+
+```typescript
+// Users
+users:getOrCreate(email, clerkId?)  // Get or create user
+users:addCredits(userId, amount)     // Add/subtract credits
+users:getBalance(userId)             // Get balance
+users:get(userId)                    // Get user by ID
+users:getByEmail(email)              // Get user by email
+
+// Purchases
+purchases:create(userId, apiId, credentials, expiresAt?)
+purchases:listByUser(userId)
+purchases:getByUserAndApi(userId, apiId)
+purchases:updateStatus(purchaseId, status)
+
+// Transactions
+transactions:log(userId, type, amount, description)
+transactions:listByUser(userId, limit?)
+```
+
+### Dev Commands
+
+```bash
+cd backend
+npx convex dev        # Start dev mode
+npx convex deploy     # Deploy to prod
+```
+
+## File Structure
+
+```
+api-discovery/
+├── README.md
+├── package.json
+├── tsconfig.json
+├── CONCEPT.md           # Original research
+├── src/
+│   ├── index.ts         # MCP server entry
+│   ├── types.ts         # TypeScript types
+│   ├── discovery.ts     # Search engine
+│   ├── credits.ts       # Credit system
+│   ├── test.ts          # Test script
+│   └── registry/
+│       └── apis.json    # API definitions
+└── backend/
+    └── convex/
+        ├── schema.ts
+        ├── users.ts
+        ├── purchases.ts
+        └── transactions.ts
+```
+
+## Development
+
+```bash
+# Watch mode
+pnpm dev
+
+# Build
+pnpm build
+
+# Test
+pnpm test
+```
+
+## License
+
+MIT - NordSym

package/backend/convex/README.md

@@ -0,0 +1,90 @@
+# Welcome to your Convex functions directory!
+
+Write your Convex functions here.
+See https://docs.convex.dev/functions for more.
+
+A query function that takes two arguments looks like:
+
+```ts
+// convex/myFunctions.ts
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+export const myQueryFunction = query({
+  // Validators for arguments.
+  args: {
+    first: v.number(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Read the database as many times as you need here.
+    // See https://docs.convex.dev/database/reading-data.
+    const documents = await ctx.db.query("tablename").collect();
+
+    // Arguments passed from the client are properties of the args object.
+    console.log(args.first, args.second);
+
+    // Write arbitrary JavaScript here: filter, aggregate, build derived data,
+    // remove non-public properties, or create new objects.
+    return documents;
+  },
+});
+```
+
+Using this query function in a React component looks like:
+
+```ts
+const data = useQuery(api.myFunctions.myQueryFunction, {
+  first: 10,
+  second: "hello",
+});
+```
+
+A mutation function looks like:
+
+```ts
+// convex/myFunctions.ts
+import { mutation } from "./_generated/server";
+import { v } from "convex/values";
+
+export const myMutationFunction = mutation({
+  // Validators for arguments.
+  args: {
+    first: v.string(),
+    second: v.string(),
+  },
+
+  // Function implementation.
+  handler: async (ctx, args) => {
+    // Insert or modify documents in the database here.
+    // Mutations can also read from the database like queries.
+    // See https://docs.convex.dev/database/writing-data.
+    const message = { body: args.first, author: args.second };
+    const id = await ctx.db.insert("messages", message);
+
+    // Optionally, return a value from your mutation.
+    return await ctx.db.get("messages", id);
+  },
+});
+```
+
+Using this mutation function in a React component looks like:
+
+```ts
+const mutation = useMutation(api.myFunctions.myMutationFunction);
+function handleButtonPress() {
+  // fire and forget, the most common way to use mutations
+  mutation({ first: "Hello!", second: "me" });
+  // OR
+  // use the result once the mutation has completed
+  mutation({ first: "Hello!", second: "me" }).then((result) =>
+    console.log(result),
+  );
+}
+```
+
+Use the Convex CLI to push your functions to a deployment. See everything
+the Convex CLI can do by running `npx convex -h` in your project root
+directory. To learn more, launch the docs with `npx convex docs`.

package/backend/convex/_generated/api.d.ts

@@ -0,0 +1,55 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as apiKeys from "../apiKeys.js";
+import type * as purchases from "../purchases.js";
+import type * as transactions from "../transactions.js";
+import type * as users from "../users.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+
+declare const fullApi: ApiFromModules<{
+  apiKeys: typeof apiKeys;
+  purchases: typeof purchases;
+  transactions: typeof transactions;
+  users: typeof users;
+}>;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export declare const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+>;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export declare const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+>;
+
+export declare const components: {};

package/backend/convex/_generated/api.js

@@ -0,0 +1,23 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import { anyApi, componentsGeneric } from "convex/server";
+
+/**
+ * A utility for referencing Convex functions in your app's API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api = anyApi;
+export const internal = anyApi;
+export const components = componentsGeneric();

package/backend/convex/_generated/dataModel.d.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/backend/convex/_generated/server.d.ts

@@ -0,0 +1,143 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const query: QueryBuilder<DataModel, "public">;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const mutation: MutationBuilder<DataModel, "public">;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export declare const action: ActionBuilder<DataModel, "public">;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * This differs from the {@link MutationCtx} because all of the services are
+ * read-only.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;