npm package: @geniusaisolutions/connect
Description: Developer-first framework for connecting external apps to LLM/RAG/MCP workflows.
Latest version: 1.0.0

# @geniusaisolutions/connect

A framework-agnostic, AI-optional package for connecting external applications (GitHub, Google Drive, Jira) into normalized connect/sync/search/webhook/retrieve workflows.

## Release bar

- Node.js `20+`
- `npm run release:verify` must pass before packing or publishing
- `npm run release:pack` validates the npm tarball contents
- `npm run check:package-exports` validates ESM and CJS entrypoints

## Current implementation status

- Core API factory: `createConnectKit(config)`
- Core operations: `connect`, `connections`, `search`, `retrieve`, `sync`, `webhooks`
- Provider introspection API: `kit.providers.list()` and `kit.providers.describe(id)`
- Optional MCP server: `kit.mcp?.createServer()`
- Optional background worker runtime: `createConnectJobWorker({ kit, queue, ... })`
- Built-in provider connectors: `github`, `google-drive`, `jira`
- Storage adapter: Postgres (`PostgresStorageAdapter`) and in-memory testing adapter
- Framework adapters (optional wrappers): Express, Next.js, Fastify, NestJS, Serverless
- AI dependencies in core: none (semantic retrieval is interface-based and optional)

## Stability

`@geniusaisolutions/connect` `1.0.0` is the first stable release of the package API.

This release commits to:

- semantic versioning for the public kit API and exported framework adapters
- built-in provider support for `github`, `google-drive`, and `jira`
- Node.js `20+`
- a release gate that includes linting, typechecking, unit and fixture tests, packaging checks, docs audits, a real Postgres integration check, and an example build audit

## Install

```bash
npm install @geniusaisolutions/connect
```

The published package is `sideEffects: false` and ships only the compiled `dist` artifacts plus root metadata files.

## Runnable Example

A Dockerized Next.js example now lives at `examples/nextjs-docker`.

It demonstrates:

- GitHub, Google Drive, and Jira OAuth connect + callback handling
- Postgres-backed storage initialization
- active connection listing
- sync, search, retrieve, and webhook routes
- a minimal OpenAI reasoning route built on top of package retrieval
- disconnect behavior that removes the connection from normal read paths

Automated verification currently covers the example app typecheck and production build. Docker startup, live OAuth, Postgres runtime behavior, and webhook delivery remain manual validation flows for the example application.

Quick start:

```bash
cd examples/nextjs-docker
cp .env.example .env
npm --prefix ../.. run generate:encryption-key
# set ENCRYPTION_KEY, OPENAI_API_KEY, and at least one provider credential set
# see examples/nextjs-docker/PROVIDER_SETUP_GUIDES.md for provider-specific setup

docker compose up --build
```

## Minimal usage

```ts
import { createConnectKit, PostgresStorageAdapter } from '@geniusaisolutions/connect';

const storage = new PostgresStorageAdapter({
  connectionString: process.env.DATABASE_URL!
});

await storage.initialize();

const kit = createConnectKit({
  appUrl: process.env.APP_URL!,
  encryptionKey: process.env.ENCRYPTION_KEY!,
  providers: ['github', 'google-drive', 'jira'],
  storage,
  security: {
    allowedRedirectUris: [
      `${process.env.APP_URL}/api/connect/github/callback`,
      `${process.env.APP_URL}/api/connect/google-drive/callback`,
      `${process.env.APP_URL}/api/connect/jira/callback`
    ],
    oauthStateTtlSeconds: 600,
    webhookReplayWindowSeconds: 300
  },
  features: {
    inlineSync: true,
    mcp: true
  }
});

const start = await kit.connect.start({
  provider: 'github',
  tenantId: 'tenant-1',
  userId: 'user-1'
});

console.log(start.authorizationUrl);
```

## Environment variables for built-in providers

- GitHub: `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
- Google Drive: `GOOGLE_DRIVE_CLIENT_ID`/`GOOGLE_CLIENT_ID`, `GOOGLE_DRIVE_CLIENT_SECRET`/`GOOGLE_CLIENT_SECRET`
- Jira: `JIRA_CLIENT_ID`, `JIRA_CLIENT_SECRET`, `JIRA_CLOUD_ID`

## Optional framework adapters

- `@geniusaisolutions/connect/express`
- `@geniusaisolutions/connect/nextjs`
- `@geniusaisolutions/connect/fastify`
- `@geniusaisolutions/connect/nestjs`
- `@geniusaisolutions/connect/serverless`

These are thin wrappers over the same core kit.

## Validation commands

```bash
npm run release:verify
npm run check:postgres
npm run check:example:build
npm run release:pack
npm run check:package-exports
```

`npm run release:verify` runs lint, typecheck, tests, build, the Postgres integration audit, docs audits, the core no-forced-AI dependency audit, traceability audit, load smoke, package export checks, pack checks, and the example app build audit.

## Publish checklist

```bash
npm version <patch|minor|major>
npm run release:verify
npm publish --access public --provenance
```

Record user-visible changes in [`CHANGELOG.md`](./CHANGELOG.md) before publishing.

## Verification artifacts

- `artifacts/test-report.json`
- `artifacts/coupling/core-dependency-audit.json`
- `artifacts/load-smoke.json`
- `artifacts/traceability-audit.json`
- `artifacts/docs-completion-audit.json`
- `artifacts/docs-link-audit.json`
- `artifacts/docs-finalization-log.json`
- `artifacts/docs-provider-parity-audit.json`
- `artifacts/docs-functional-audit.json`
- `spec/requirements.csv`
- `spec/traceability.csv`

## License

MIT