feat: add CodebuffTransactionFn type and improve BillingTransactionFn docs

- Add CodebuffTransaction and CodebuffTransactionFn types to @codebuff/internal/db
  for fully-typed Drizzle transaction usage in production code
- Improve BillingTransactionFn documentation explaining why any is needed
  (Drizzle PgTransaction signatures incompatible with BillingDbConnection)
- Document when to use CodebuffTransactionFn vs BillingTransactionFn

Author: brandonkachen

common/src/types/contracts/billing.ts

@@ -227,22 +227,34 @@ export type BillingDbConnection = {
 }
 
 /**
- * Transaction callback type.
- * This matches the signature of drizzle's db.transaction method.
+ * Transaction callback type for dependency injection.
  * 
- * Note: The callback parameter uses `any` because the real Drizzle transaction
- * type (`PgTransaction`) has many additional properties (schema, rollback, etc.)
- * that our minimal `BillingDbConnection` doesn't include. Using `any` allows
- * both the real transaction and mock implementations to work.
+ * This type uses `any` for the callback parameter to allow both:
+ * - Real Drizzle transactions (which have complex generic types)
+ * - Mock implementations using `BillingDbConnection`
+ * 
+ * The `any` is necessary because Drizzle's `PgTransaction` type has method
+ * signatures incompatible with our simplified `BillingDbConnection` interface.
+ * Using a union or intersection type creates uncallable method signatures.
+ * 
+ * For production code that needs full Drizzle type safety (no DI), use
+ * `CodebuffTransactionFn` from `@codebuff/internal/db` instead.
  * 
- * In tests, you can pass a mock that satisfies `BillingDbConnection`:
  * @example
  * ```typescript
+ * // In tests - create mocks that satisfy BillingDbConnection
  * const mockTransaction: BillingTransactionFn = async (callback) => {
  *   const mockDb = createMockDb({ users: [...] })
  *   return callback(mockDb)
  * }
+ * 
+ * // In production - use with db.transaction.bind(db)
+ * const transaction = deps.transaction ?? db.transaction.bind(db)
+ * await transaction(async (tx) => { ... })
  * ```
+ * 
+ * @see CodebuffTransactionFn in `@codebuff/internal/db` for fully-typed production use
+ * @see BillingDbConnection for the minimal interface that mocks should implement
  */
 export type BillingTransactionFn = <T>(
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -300,7 +312,12 @@ export type GetOrganizationUsageResponseFn = (params: {
 // ============================================================================
 
 /**
- * Dependencies for triggerMonthlyResetAndGrant
+ * Dependencies for triggerMonthlyResetAndGrant.
+ * 
+ * Note: The `transaction` field uses `BillingTransactionFn` which accepts
+ * `BillingDbConnection` in the callback. This works for testing with mocks.
+ * In production code, the billing package uses `CodebuffTransactionFn` from
+ * `@codebuff/internal/db` which provides full Drizzle type safety.
  */
 export type TriggerMonthlyResetAndGrantDeps = {
   db?: BillingDbConnection

packages/billing/src/grant-credits.ts

@@ -18,10 +18,10 @@ import type {
 } from '@codebuff/common/types/contracts/billing'
 import type { GrantType } from '@codebuff/internal/db/schema'
 
-type CreditGrantSelect = typeof schema.creditLedger.$inferSelect
+// Local type alias for the transaction object - extracts the actual type from db.transaction
 type DbTransaction = Parameters<typeof db.transaction>[0] extends (
   tx: infer T,
-) => any
+) => unknown
   ? T
   : never
 
@@ -328,11 +328,18 @@ export async function processAndGrantCredit(params: {
  * @param deps Optional dependencies for testing (transaction function)
  * @returns true if the grant was found and revoked, false otherwise
  */
+/**
+ * Dependencies for revokeGrantByOperationId (for testing)
+ */
+export interface RevokeGrantByOperationIdDeps {
+  transaction?: BillingTransactionFn
+}
+
 export async function revokeGrantByOperationId(params: {
   operationId: string
   reason: string
   logger: Logger
-  deps?: { transaction?: BillingTransactionFn }
+  deps?: RevokeGrantByOperationIdDeps
 }): Promise<boolean> {
   const { operationId, reason, logger, deps = {} } = params
   const transaction = deps.transaction ?? db.transaction.bind(db)

packages/internal/src/db/index.ts

@@ -7,6 +7,8 @@ import * as schema from './schema'
 
 import type { CodebuffPgDatabase } from './types'
 
+export type { CodebuffPgDatabase, CodebuffTransaction, CodebuffTransactionFn } from './types'
+
 const client = postgres(env.DATABASE_URL)
 
 export const db: CodebuffPgDatabase = drizzle(client, { schema })

packages/internal/src/db/types.ts

@@ -1,8 +1,47 @@
 import type * as schema from './schema'
 import type { PgDatabase } from 'drizzle-orm/pg-core'
 import type { PostgresJsQueryResultHKT } from 'drizzle-orm/postgres-js'
+import type { ExtractTablesWithRelations } from 'drizzle-orm'
+import type { PgTransaction } from 'drizzle-orm/pg-core'
 
 export type CodebuffPgDatabase = PgDatabase<
   PostgresJsQueryResultHKT,
   typeof schema
 >
+
+/**
+ * The type of a Drizzle transaction object for Codebuff's database.
+ * This is the `tx` parameter type in `db.transaction(async (tx) => { ... })`.
+ * 
+ * Use this type when you need the full Drizzle transaction capabilities.
+ * For DI/testing scenarios where you only need basic CRUD operations,
+ * use `BillingDbConnection` from `@codebuff/common/types/contracts/billing`.
+ */
+export type CodebuffTransaction = PgTransaction<
+  PostgresJsQueryResultHKT,
+  typeof schema,
+  ExtractTablesWithRelations<typeof schema>
+>
+
+/**
+ * Type for the db.transaction function.
+ * Use this to properly type transaction functions in production code.
+ * 
+ * @example
+ * ```typescript
+ * import type { CodebuffTransactionFn } from '@codebuff/internal/db/types'
+ * 
+ * async function myFunction(params: {
+ *   deps?: { transaction?: CodebuffTransactionFn }
+ * }) {
+ *   const transaction = params.deps?.transaction ?? db.transaction.bind(db)
+ *   return transaction(async (tx) => {
+ *     // tx is fully typed as CodebuffTransaction
+ *     await tx.insert(schema.user).values({ ... })
+ *   })
+ * }
+ * ```
+ */
+export type CodebuffTransactionFn = <T>(
+  callback: (tx: CodebuffTransaction) => Promise<T>,
+) => Promise<T>