Skip to main content

cortexa.connectors

Project Overview​

cortexa.connectors is a private TypeScript npm workspace for Cortexa connector packages. It currently represents a provider-oriented package repository with one implemented connector package: Google Drive.

The repository exists to keep provider SDK usage, provider API behavior, and provider-to-Cortexa metadata mapping outside downstream Cortexa applications. Consumers can call connector packages through Cortexa contract types instead of depending directly on provider SDK response shapes.

This repository is a library workspace, not a runtime application, UI application, API service, database owner, infrastructure module, or documentation-only repository.

Key Responsibilities​

  • Own provider connector package implementations.
  • Construct provider API clients from caller-supplied credentials.
  • Expose small TypeScript connector APIs for supported provider operations.
  • Map provider file metadata into shared @cortexa/contracts types.
  • Keep provider SDK request details inside provider packages.
  • Leave OAuth lifecycle, credential storage, persistence, indexing, orchestration, retries, and product workflows to consuming systems.

Current Status​

Implemented Capabilities​

  • Private npm workspace using packages/*.
  • Google Drive connector package at packages/google-drive.
  • @cortexa/connectors-google-drive package manifest with built entrypoints at dist/index.js and dist/index.d.ts.
  • Public source exports for GoogleDriveConnector and ListFilesOptions.
  • Basic connector health check.
  • Google Drive file listing with optional parent filtering.
  • Recursive folder traversal.
  • Inclusion of Google Drive files reported by sharedWithMe = true.
  • Direct Google Drive file download with normalized DownloadedFile payloads.
  • Google Drive metadata mapping into Cortexa connector file contracts.
  • Package-local development examples.
  • Generated repository tree workflow through npm run docs:tree.

Foundational Or Partial Capabilities​

  • includeShared includes files shared with the authenticated Google account, but does not implement full Google Shared Drives behavior.
  • downloadFile uses direct media download and does not export Google Workspace-native Docs, Sheets, or Slides files.
  • Listing currently reads the first page returned by each request.
  • Package examples exist for development, but no automated test script is currently defined.
  • The workspace structure supports additional provider packages, but only Google Drive is implemented today.

Packages And Entry Points​

PathPackagePurposePublic entrypoints
packages/google-drive@cortexa/connectors-google-driveGoogle Drive provider connector package for Cortexa consumers.src/index.ts exports GoogleDriveConnector and ListFilesOptions; package main and types point to generated dist output.

Package-specific usage, API notes, provider behavior, examples, and limitations are documented in packages/google-drive/README.md.

Getting Started​

Install workspace dependencies from the repository root:

npm install

Build the Google Drive package:

npm run build --workspace=@cortexa/connectors-google-drive

Refresh the generated repository tree:

npm run docs:tree

Useful starting points for code exploration:

  • packages/google-drive/src/index.ts
  • packages/google-drive/src/google-drive.connector.ts
  • packages/google-drive/src/services
  • packages/google-drive/src/mappers
  • packages/google-drive/examples

This repository depends on TypeScript, npm workspaces, the googleapis SDK in the Google Drive package, and shared Cortexa contracts from @cortexa/contracts.

Documentation​

  • docs/ARCHITECTURE.md: architectural source of truth for repository purpose, ecosystem role, responsibilities, boundaries, contracts, constraints, and design principles.
  • docs/REPOSITORY.md: repository organization and code placement source of truth.
  • docs/repository/project-tree.md: generated current file and folder inventory. Regenerate it with npm run docs:tree; do not edit it manually.
  • packages/google-drive/README.md: package-level guide for the Google Drive connector package.

No docs/DATABASE.md, docs/ECOSYSTEM.md, docs/API.md, or docs/OPERATIONS.md document is currently present in this repository.

Architecture Summary​

The repository is organized around isolated provider connector packages. The implemented Google Drive package owns its provider client construction, provider operations, metadata mapping, public facade, package manifest, and examples.

The public boundary is the connector package API. Consumers provide runtime credentials and operation options, then receive Cortexa contract objects from @cortexa/contracts. Raw provider SDK responses remain package implementation details.

This module does not own authentication lifecycle, credential persistence, indexing, durable orchestration, UI workflows, deployment infrastructure, or product-specific behavior. See docs/ARCHITECTURE.md for architectural details.

Repository Organization Summary​

The root owns workspace metadata, dependency locking, shared TypeScript defaults, repository scripts, and this landing page. Repository-level documentation lives under docs. Generated repository inventory lives under docs/repository/project-tree.md. Provider packages live under packages/*. Repository tooling lives under scripts.

The current provider package is packages/google-drive, with source under src, development examples under examples, package configuration in package.json and tsconfig.json, and package-specific documentation in its README.

See docs/REPOSITORY.md for repository navigation and code placement guidance. See docs/repository/project-tree.md for the generated current file tree.

Contributing​

Follow the existing workspace and package conventions. Review docs/ARCHITECTURE.md and docs/REPOSITORY.md before making structural or architectural changes.

Keep provider-specific behavior inside the owning provider package. Keep shared Cortexa contracts in @cortexa/contracts, not in this repository. Keep package usage details in package READMEs and durable repository guidance under docs.

When repository structure changes, regenerate docs/repository/project-tree.md with npm run docs:tree. Keep documentation aligned with implementation and avoid editing generated outputs manually.

Documentation Philosophy​

README.md is the repository entrypoint and summary document.

docs/ARCHITECTURE.md is the architectural source of truth.

docs/REPOSITORY.md is the repository organization and code placement source of truth.

docs/repository/project-tree.md is the generated current repository tree.

Package-level README files are package-specific usage and entrypoint guides.

Detailed documentation belongs under docs or in package-level README files. This README should stay concise, summarize only stable high-level context, and route readers to the right source of truth.