@geenius/adapters 0.1.0

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @mxn2020

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,16 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+## Describe the bug
+
+## Steps to reproduce
+
+## Expected behavior
+
+## Environment
+- Package version:
+- Node version:
+- OS:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,11 @@
+---
+name: Feature Request
+about: Suggest a new feature
+labels: enhancement
+---
+
+## Problem
+
+## Proposed solution
+
+## Alternatives considered

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## What
+
+## Why
+
+## How
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] `pnpm changeset` run (if applicable)
+- [ ] Documentation updated

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm lint
+      - run: pnpm test

package/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+on:
+  push:
+    branches: [main]
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - uses: changesets/action@v1
+        with:
+          publish: pnpm changeset publish
+          version: pnpm changeset version
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.nvmrc

@@ -0,0 +1 @@
+22

package/.project/ACCOUNT.yaml

@@ -0,0 +1,4 @@
+owner: Mehdi Nabhani
+email: mehdi@geenius.app
+github: mxn2020
+organization: geenius

package/.project/IDEAS.yaml

@@ -0,0 +1,7 @@
+ideas:
+  - title: "CLI scaffolding"
+    description: "Add a create command to geenius-cli for this package"
+    priority: medium
+  - title: "Vue adapter"
+    description: "Add Vue 3 support alongside React and SolidJS"
+    priority: low

package/.project/PROJECT.yaml

@@ -0,0 +1,11 @@
+name: geenius-adapters
+description: "Geenius Adapters — Backend adapter abstraction layer for auth, db, payments, AI, and storage"
+category: library
+priority: high
+tags:
+  - geenius
+  - npm-package
+  - react
+  - solidjs
+deploy_url: null
+npm_scope: "@geenius-adapters"

package/.project/ROADMAP.yaml

@@ -0,0 +1,15 @@
+version: "0.1"
+milestones:
+  - name: "v0.1.0 — Initial Release"
+    status: in-progress
+    items:
+      - "Core shared types and logic"
+      - "React hooks and components"
+      - "SolidJS primitives"
+      - "npm publishing via Changesets"
+  - name: "v0.2.0 — Stability"
+    status: planned
+    items:
+      - "Test coverage ≥ 50%"
+      - "API documentation"
+      - "Convex adapter"

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-03-21
+
+### Added
+- Initial release

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at conduct@geenius.app.
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to @geenius-adapters
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+```bash
+git clone https://github.com/mxn2020/geenius-adapters.git
+cd geenius-adapters
+pnpm install
+pnpm build
+pnpm test
+```
+
+## Pull Request Process
+
+1. Fork the repo and create a feature branch from `main`
+2. Add or update tests as appropriate
+3. Run `pnpm changeset` to describe your changes for the changelog
+4. Open a PR against `main`
+
+## Code Style
+
+- TypeScript strict mode
+- ESLint + Prettier formatting
+- Conventional commits preferred

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mehdi Nabhani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# `@geenius/adapters`
+
+> The architectural lynchpin of the Geenius ecosystem — a unified adapter layer that makes backend services interchangeable with a one-file swap.
+
+---
+
+## Overview
+
+`@geenius/adapters` defines **standard interfaces** for six infrastructure domains and provides concrete implementations for each. Any frontend component talks exclusively to an adapter interface — never to a database or service directly.
+
+This is what makes "swap Convex for Supabase" a single-file change instead of a months-long rewrite.
+
+### Adapter Domains
+
+| Domain | Interface | Providers |
+|--------|-----------|-----------|
+| **DB** | `DbAdapter` | `localStorage`, Convex, Supabase, Neon, MongoDB |
+| **Auth** | `AuthAdapter` | `localStorage`, Better Auth, Convex Auth, Clerk, Supabase Auth |
+| **Payments** | `PaymentsAdapter` | `localStorage`, Stripe, noop |
+| **AI** | `AiAdapter` | `localStorage`, OpenAI, Anthropic, Gemini, Ollama, CF AI Gateway, Vercel AI SDK |
+| **File Storage** | `FileStorageAdapter` | `localStorage`, R2, S3, Uploadthing, Supabase Storage, Convex Storage, Minio |
+| **Admin** | `AdminAdapter` | `localStorage` |
+
+---
+
+## Installation
+
+```bash
+pnpm add @geenius/adapters
+```
+
+## Sub-package Exports
+
+```typescript
+import { configureAdapters, createConvexDbAdapter }      from '@geenius/adapters'          // shared (default)
+import { AdapterProvider, useDb, useAuth, useAi }        from '@geenius/adapters/react'     // React hooks
+import { AdapterProvider, createDb, createAuth }          from '@geenius/adapters/solidjs'   // SolidJS primitives
+import { adapterTables }                                   from '@geenius/adapters/convex'    // Convex schema
+import { AdaptersPage, AdapterCard }                       from '@geenius/adapters/react-css' // Styled React components
+import { AdaptersPage, AdapterCard }                       from '@geenius/adapters/solidjs-css' // Styled SolidJS components
+```
+
+---
+
+## Quick Start
+
+### 1. Configure adapters at app startup
+
+```typescript
+import { configureAdapters } from '@geenius/adapters'
+import { createConvexDbAdapter } from '@geenius/adapters'
+
+// Call once before rendering
+configureAdapters({
+  db:       { provider: 'convex' },
+  auth:     { provider: 'better-auth' },
+  ai:       { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
+  storage:  { provider: 'r2' },
+  payments: { provider: 'stripe' },
+})
+```
+
+### 2. Wrap your app with AdapterProvider (React)
+
+```tsx
+import { AdapterProvider } from '@geenius/adapters/react'
+import { createBetterAuthAdapter } from '@geenius/adapters'
+import { createConvexDbAdapter } from '@geenius/adapters'
+
+export function App() {
+  return (
+    <AdapterProvider
+      adapters={{
+        db:   createConvexDbAdapter({ client: convex, functions: myFns }),
+        auth: createBetterAuthAdapter({ client: authClient }),
+        ai:   createOpenAiAdapter({ apiKey: process.env.OPENAI_API_KEY }),
+      }}
+      healthCheck
+    >
+      <Router />
+    </AdapterProvider>
+  )
+}
+```
+
+### 3. Use adapters in components
+
+```tsx
+import { useAuth, useDb, useAi } from '@geenius/adapters/react'
+
+export function Dashboard() {
+  const auth = useAuth()
+  const db   = useDb()
+  const ai   = useAi()
+
+  async function handleSignIn() {
+    await auth.signIn('user@example.com', 'password')
+  }
+
+  async function handleOAuth() {
+    const { url } = await auth.signInWithOAuth('google', { redirectUrl: '/dashboard' })
+    window.location.href = url
+  }
+
+  async function handleChat() {
+    const response = await ai.chat([{ role: 'user', content: 'Hello!' }])
+    console.log(response.content)
+  }
+}
+```
+
+---
+
+## Prototyping with localStorage (Pronto tier)
+
+Every domain ships a `localStorage` implementation for zero-config prototyping:
+
+```typescript
+import {
+  createLocalStorageAuthAdapter,
+  createLocalStorageDbAdapter,
+  createLocalStorageAiAdapter,
+  createLocalStorageFileAdapter,
+  createLocalStoragePaymentsAdapter,
+  createLocalStorageAdminAdapter,
+  createNoopPaymentsAdapter,
+} from '@geenius/adapters'
+```
+
+These adapters persist data in the browser's localStorage with no external dependencies. Upgrade to real adapters by replacing a single file.
+
+---
+
+## Tier Gating
+
+```typescript
+import { isFeatureAvailable, isPackageAvailable, getUpgradeFeatures } from '@geenius/adapters'
+
+isFeatureAvailable('admin', 'pronto')    // → false
+isFeatureAvailable('admin', 'lancio')   // → true
+isFeatureAvailable('ai-magic', 'studio') // → true
+
+getUpgradeFeatures('pronto', 'lancio')
+// → ['admin', 'payments', 'blog', 'file-storage', 'ai-workflow', 'ai-embeddings']
+```
+
+---
+
+## Provider Registry
+
+```typescript
+import { PROVIDER_REGISTRY, getProvidersForDomain, getProviderMeta } from '@geenius/adapters'
+
+getProvidersForDomain('ai')
+// → [{ id: 'localStorage', tier: 'pronto' }, { id: 'openai', tier: 'lancio' }, ...]
+
+getProviderMeta('payments', 'stripe')
+// → { id: 'stripe', name: 'Stripe', domain: 'payments', tier: 'lancio', ... }
+```
+
+---
+
+## Adapter Interface Contracts
+
+All interfaces are **async (Promise-based)**, generic, and framework-agnostic. Swapping a provider only requires replacing the adapter factory call — no changes to consumers.
+
+```typescript
+// AuthAdapter — all providers
+interface AuthAdapter {
+  signIn(email: string, password: string): Promise<AuthSession>
+  signUp(email: string, password: string, name?: string): Promise<AuthSession>
+  signInWithOAuth(provider: OAuthProvider, options?: { redirectUrl?: string }): Promise<{ url: string }>
+  signOut(): Promise<void>
+  getSession(): Promise<AuthSession | null>
+  getUser(): Promise<AuthUser | null>
+  updateUser(updates: Partial<Pick<AuthUser, 'name' | 'image'>>): Promise<AuthUser | null>
+}
+
+// AiAdapter — all providers (stream is optional, falls back to chat)
+interface AiAdapter {
+  chat(messages: ChatMessage[], options?: AiOptions): Promise<ChatResponse>
+  complete(prompt: string, options?: AiOptions): Promise<string>
+  embed(text: string | string[]): Promise<number[][]>
+  stream?(messages: ChatMessage[], options?: AiOptions): AsyncIterable<string>
+}
+```
+
+---
+
+## Tier Availability
+
+| Tier | Description |
+|------|-------------|
+| **Pronto** | Prototype-ready. localStorage only. Zero external deps. |
+| **Lancio** | Production-ready. Real backends: Convex, Stripe, Better Auth, R2. |
+| **Studio** | Full ecosystem. All Lancio providers + AI Magic, Analytics, Teams, and more. |
+
+---
+
+## License
+
+MIT — © Antigravity HQ

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.x.x   | ✅        |
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities by emailing **security@geenius.app**.
+
+Do **not** open a public GitHub issue for security vulnerabilities.
+
+We will acknowledge receipt within 48 hours and provide a detailed response within 5 business days.

package/SUPPORT.md

@@ -0,0 +1,8 @@
+# Support
+
+## Getting Help
+
+- 📖 [Documentation](https://docs.geenius.app)
+- 🐛 [Bug Reports](https://github.com/mxn2020/geenius-adapters/issues/new?template=bug_report.md)
+- 💡 [Feature Requests](https://github.com/mxn2020/geenius-adapters/issues/new?template=feature_request.md)
+- 📧 Email: support@geenius.app

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@geenius/adapters",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm -r build",
+    "lint": "pnpm -r lint",
+    "test": "pnpm -r test",
+    "clean": "pnpm -r clean"
+  },
+  "devDependencies": {
+    "typescript": "~6.0.2"
+  },
+  "author": "Antigravity HQ",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./packages/shared/dist/index.d.ts",
+      "import": "./packages/shared/dist/index.js"
+    },
+    "./shared": {
+      "types": "./packages/shared/dist/index.d.ts",
+      "import": "./packages/shared/dist/index.js"
+    },
+    "./convex": {
+      "types": "./packages/convex/dist/index.d.ts",
+      "import": "./packages/convex/dist/index.js"
+    },
+    "./react": {
+      "types": "./packages/react/dist/index.d.ts",
+      "import": "./packages/react/dist/index.js"
+    },
+    "./react-css": {
+      "types": "./packages/react-css/dist/index.d.ts",
+      "import": "./packages/react-css/dist/index.js"
+    },
+    "./solidjs": {
+      "types": "./packages/solidjs/dist/index.d.ts",
+      "import": "./packages/solidjs/dist/index.js"
+    },
+    "./solidjs-css": {
+      "types": "./packages/solidjs-css/dist/index.d.ts",
+      "import": "./packages/solidjs-css/dist/index.js"
+    }
+  },
+  "main": "./packages/shared/dist/index.js",
+  "types": "./packages/shared/dist/index.d.ts"
+}

package/packages/convex/README.md

@@ -0,0 +1,64 @@
+# `@geenius-adapters/convex`
+
+> Convex backend integration for `@geenius/adapters` — registry, health logs, and adapter lifecycle management.
+
+---
+
+## Overview
+
+This sub-package provides the Convex schema, mutations, and queries needed to persist adapter registry state in a Convex backend. It tracks which adapters are registered, their current status, and health check history.
+
+## Installation
+
+This package is a private workspace dependency used by the `@geenius/adapters` root package. It is consumed via the `/convex` export:
+
+```typescript
+import { schema, registerAdapter, listAdapters } from '@geenius/adapters/convex'
+```
+
+## Schema
+
+### `adapter_registry`
+
+Stores the active adapter configuration per domain.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `domain` | string | Adapter domain (`db`, `auth`, `ai`, etc.) |
+| `provider` | string | Provider name (e.g., `convex`, `openai`) |
+| `status` | string | `active` \| `inactive` \| `error` |
+| `config` | any | Provider-specific configuration |
+
+### `adapter_health_logs`
+
+Tracks adapter health check results over time.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `adapterId` | Id | Reference to `adapter_registry` |
+| `domain` | string | Adapter domain |
+| `status` | string | Check result (`healthy` \| `unhealthy`) |
+| `latencyMs` | number | Check response time in ms |
+| `timestamp` | number | Unix timestamp |
+
+## API
+
+### Mutations
+
+- `registerAdapter(domain, provider, config?)` — Register or update an adapter for a domain
+- `updateAdapterStatus(id, status)` — Update the status of a registered adapter
+- `updateAdapter(id, updates)` — Update adapter configuration
+- `removeAdapter(id)` — Remove adapter and all associated health logs
+
+### Queries
+
+- `listAdapters()` — List all registered adapters
+- `listAdaptersByDomain(domain)` — List adapters for a specific domain
+- `getAdapter(id)` — Get a single adapter by ID
+- `getActiveAdapter(domain)` — Get the currently active adapter for a domain
+- `getAdapterStatusSummary()` — Aggregate status counts across all domains
+- `getAdapterHealthLogs(adapterId, limit?)` — Get recent health logs for an adapter
+
+---
+
+*Part of the [Geenius Boilerplate Ecosystem](https://github.com/AntigravityHQ/geenius) by Antigravity HQ*

package/packages/convex/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@geenius-adapters/convex",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Convex adapter factory and configuration for database integration",
+  "author": "Antigravity HQ",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "pnpm clean && pnpm build"
+  },
+  "peerDependencies": {
+    "convex": "^1.34.0"
+  },
+  "devDependencies": {
+    "convex": "^1.34.0",
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/packages/convex/src/adapter.ts

@@ -0,0 +1,39 @@
+import type { ConvexAdapterConfig, ConvexDbAdapter } from './types'
+
+/**
+ * Factory function to create a Convex database adapter
+ */
+export function createConvexAdapter(
+  config: ConvexAdapterConfig,
+): ConvexDbAdapter {
+  let isConnected = false
+
+  return {
+    query: async (queryFn: string, args?: Record<string, unknown>) => {
+      if (!isConnected) {
+        throw new Error('Convex adapter not initialized')
+      }
+      // Placeholder: would execute query through Convex client
+      return null
+    },
+
+    mutation: async (
+      mutationFn: string,
+      args?: Record<string, unknown>,
+    ) => {
+      if (!isConnected) {
+        throw new Error('Convex adapter not initialized')
+      }
+      // Placeholder: would execute mutation through Convex client
+      return null
+    },
+
+    isReady: () => {
+      return isConnected
+    },
+
+    disconnect: async () => {
+      isConnected = false
+    },
+  }
+}