Extend @suaveplan/better-auth-surrealdb with Better-Auth v1.6 DBAdapterInstance factory

Package: @suaveplan/better-auth-surrealdb Status: PROPOSED Type: feature (additive — preserves shipped v1.4-shape adapter)

Spec delta: ./specs/better-auth-surrealdb/spec.md

Why

@suaveplan/better-auth-surrealdb (shipped commit 2ed843a5, ~hours ago) exports createBetterAuthSurrealAdapter returning a 10-method Adapter matching Better-Auth v1.4's contract. The installed better-auth (catalog ^1.4.0 resolves to 1.6.11) expects BetterAuthOptions.database: DBAdapterInstance = (options: BetterAuthOptions) => DBAdapter<Options> — a factory returning a Kysely-flavored adapter with many more methods (transaction, createSchema, getDefaultIdField, etc.). The shapes are structurally incompatible, so createBetterAuth({ database: createBetterAuthSurrealAdapter(...) }) fails to type-check AND fails at runtime when Better-Auth invokes the missing methods.

Fix: add a v1.6-compatible factory export betterAuthSurrealAdapter(opts) that returns a DBAdapterInstance. Internally it builds the same 10-method underlying adapter we already ship and wraps it via createAdapterFactory from @better-auth/core/db — the official escape hatch Better-Auth provides for custom adapters. The existing createBetterAuthSurrealAdapter export stays unchanged (still useful for direct conformance harness usage and for hypothetical v1.4 callers).

What changes

Additive — no breaking changes to the existing surface. ADDED:

betterAuthSurrealAdapter(options): DBAdapterInstance — the v1.6 factory. Exported from root barrel + new subpath ./adapter/v1.6. Signature mirrors Better-Auth's DBAdapterInstance type: takes the parsed BetterAuthOptions at call time (inside createBetterAuth), returns the full DBAdapter.
Internally:
1. Constructs the 10-method underlying adapter via createBetterAuthSurrealAdapter(options) (the existing surface).
2. Wraps via createAdapterFactory({ ... }) from @better-auth/core/db. The wrapper presents the v1.6 DBAdapter to Better-Auth and forwards every operation through our adapter's create/findOne/findMany/update/updateMany/delete/deleteMany/count methods (the 10th method, consumeOne, is wired for atomic verification-token consumption).
3. Translates the getDefaultIdField / transaction / createSchema methods Better-Auth expects:
  - getDefaultIdField: returns "id" (default — operators override via BetterAuthSurrealAdapterOptions.modelToTable only affects table names).
  - transaction: forwards to SurrealDB's runSurrealTransaction helper from @suaveplan/surrealdb.
  - createSchema: returns BETTER_AUTH_SURREAL_SCHEMA as a string so Better-Auth's CLI flows (@better-auth/cli generate) can emit the canonical schema. Idempotent per DEFINE … OVERWRITE.
BetterAuthSurrealAdapterV16Options — type alias for the v1.6 factory's options object. Identical to BetterAuthSurrealAdapterOptions except wraps the per-call BetterAuthOptions argument the factory receives. Zod-validated via the same BetterAuthSurrealAdapterOptionsSchema.
Subpath export: ./adapter/v1.6.
README quick-start updated to show v1.6 usage as the default. The v1.4-shape adapter is documented as "advanced — direct conformance harness usage."

Out of scope

Better-Auth v1.4 support drop. The existing v1.4-shape export is preserved (no caller uses it yet, but the public surface stability is worth preserving for the conformance harness path).
Schema generation CLI integration. Better-Auth's CLI (@better-auth/cli generate --adapter @suaveplan/better-auth-surrealdb/adapter/v1.6) will work via the createSchema translation, but bundling the CLI itself is a separate package.
Transaction nesting / savepoints. SurrealDB v3's transaction model is flat; nested transaction calls degrade to the outermost transaction (matches Better-Auth's documented expectation).
Custom ID field strategies via Better-Auth's customIdField. Better-Auth's customIdField option flows through to the underlying adapter's idStrategy: "plain" behaviour (id stored as a field, SurrealDB auto-generates the record's storage id). Operators using customIdField should pass idStrategy: "plain" explicitly.

Source mapping

Genesis-original — surfaced by the add-api-plugin-auth scaffold-time blocker.

Requirement	Source
`DBAdapterInstance` factory shape	Better-Auth v1.6 `BetterAuthOptions.database` type
`createAdapterFactory` wrapper	`@better-auth/core/db` — official custom-adapter escape hatch
Transaction forwarding	`@suaveplan/surrealdb`'s `runSurrealTransaction` helper
`createSchema` returning DDL	`BETTER_AUTH_SURREAL_SCHEMA` shipped at `./schema`

Impact

Affected dependents

@suaveplan/api-plugin-auth (in-flight) — unblocks. Auth plugin's onInit will use createBetterAuth({ database: betterAuthSurrealAdapter({ client: db, ... }), ...options.betterAuth }).
Existing createBetterAuthSurrealAdapter callers (the conformance harness in tests/integration/) — unchanged.

Risk: low. Additive on the package; the new factory is a thin wrapper over the existing internal 10-method adapter, exercised by the same conformance harness against the same testcontainer.

5.3 KiB Raw Blame History