listee-libs

Overview

listee-libs is the public monorepo that hosts the Listee SDK packages. Each module is published under the @listee/* scope so downstream applications (API, web, CLI, MCP) can consume them independently. The initial release focuses on @listee/db (database access layer) and @listee/auth (token verification utilities), with @listee/types and other packages (chat, ui, sdk) landing incrementally.

Repository Layout

• packages/<name> — Individual packages with their implementation in src/ and compiled output in dist/.
• tsconfig.json — Shared TypeScript project references and strict compiler requirements.
• biome.json — Biome formatter and linter configuration.
• vitest.config.ts — Test runner configuration for the entire workspace.
• .github/workflows/ — CI pipelines based on listee-dev/listee-ci@v1 workflows.

Getting Started

1. Install Bun 1.2.22 (or later). We recommend pinning via "packageManager": "bun@1.2.22" in the root package.json for reproducibility.
2. Run bun install at the repository root (catalog-aware installation for every workspace).
3. Use bun run lint, bun run build, and bun run test to verify changes locally.
4. Initialize Changesets with bun run changeset init if you are bootstrapping a fresh clone.

Packages

@listee/db

• Provides a thin Postgres + Drizzle ORM layer with connection caching for local development.
• Requires POSTGRES_URL to be defined before calling createPostgresConnection.
• Exposes helpers:
  • createPostgresConnection — returns a cached postgres client (disabled in production); accepts optional overrides.
  • db — shared drizzle-orm database instance backed by the cached connection.
  • createRlsClient/createDrizzle — wrap transactions with Supabase-style RLS claims and role switching.
• Publishes generated types alongside compiled output (sideEffects: false for optimal tree-shaking).
• Ships with Bun-based unit tests (packages/db/src/index.test.ts) that mock postgres/drizzle-orm. Run bun test from the repo root to execute them.

@listee/auth

• Exposes reusable authentication providers under packages/auth/src/authentication/.
• createSupabaseAuthentication validates Supabase-issued JWT access tokens against the project's JWKS (/auth/v1/.well-known/jwks.json), enforces issuer/audience/role constraints, and returns a typed SupabaseToken payload.
• Shared utilities (shared.ts, errors.ts) handle predictable error surfaces; tests live beside the implementation (supabase.test.ts) and exercise positive/negative paths.
• The package emits declarations from src/ only; test files are excluded from dist/ via tsconfig.json.

Contribution Notes

• Follow the guidance in AGENTS.md for agent automation workflows and repository conventions.
• Keep documentation and code comments in English.
• Coordinate feature work through focused branches (feature/..., chore/..., etc.) and submit PRs with clear descriptions, linked issues, and test evidence.

Architecture Guidelines

Responsibility Boundaries

• routes only depend on queries, translate the return values into HTTP responses, and decide status codes.
• queries orchestrate the necessary services and repositories for each use case and accept dependencies via factories so they remain easy to test.
• services may depend on repositories (never the other way around). When a service grows large, consider moving domain logic under a dedicated domain/ module and keeping application services thin.
• repositories sit at the bottom layer and encapsulate external SDK calls, SQL, or KV access. They should return plain TypeScript/domain types (string, Date, structured objects) to upstream layers.

Dependency Flow

Keep a single direction: routes → queries → (services → repositories). With the stack arranged this way you can reuse everything below queries across different runtimes (e.g., Cloudflare Workers) and mock each layer in isolation during tests.

Authentication vs Authorization

• Treat authentication (identifying who the caller is) and authorization (deciding what that caller may do) as separate concerns under the auth package.
• Place authentication adapters in packages/auth/src/authentication/ and expose helpers such as getAuthenticatedUser(request) so each runtime can plug in its own token/session verification.
• Organize authorization policies under packages/auth/src/authorization/ with domain-specific modules (e.g., policies/chat.ts providing canAccessChat). Policies may declare repository interfaces that the application injects, keeping policy evaluation independent from data fetching details.
• The recommended execution order for an authenticated endpoint is Route Handler → Authentication → Queries → Authorization → Services/Repositories. Queries receive the authenticated actor (for example, via context) and call the relevant authorization policy before touching domain services.

Release Process

Changesets drive versioning and publishing.

1. Run bun run changeset for every meaningful change. Select the affected packages and bump type, then commit the generated .changeset/*.md file.
2. When the Changeset PR merges to main, the CI pipeline creates a “Version Packages” PR. Merge it to stage versions.
3. A second merge to main triggers the release job. Approve the production environment gate in Actions to publish to npm.
4. Verify the published versions with npm view @listee/<package> version and update release notes as needed.

Trusted Publishing requirements

• Each package package.json must declare:

  "publishConfig": { "access": "public", "provenance": true },
  "repository": { "type": "git", "url": "https://github.com/listee-dev/listee-libs.git" }

• npm must grant Trusted Publisher access to listee-dev/listee-libs (workflow ci.yml, environment production). No permanent NPM_TOKEN is required.
• The reusable release.yml from listee-ci uses npx changeset version/publish with npm@latest, so local releases can be simulated via npx changeset version && npx changeset publish.