skills/plugins/library-navigator/skills/sp-better-auth-surrealdb/SKILL.md

name, description

name	description
sp-better-auth-surrealdb	Better-Auth Adapter for SurrealDB v3 — 17-table schema, Where[]→SurrealQL compilation, record-link prefixing, id strategies, conformance harness.

Architecture

Component	Responsibility
createBetterAuthSurrealAdapter	Returns 10-method Better-Auth Adapter (create/find/update/delete/count)
betterAuthSurrealAdapter	v1.6 integration surface wrapping createAdapterFactory
compileWhere	Translates Better-Auth Where[] filters to parameterised SurrealQL WHERE
compileSelect	Compiles select?: string[] projection into SurrealQL column list
compileSortBy	Compiles sortBy into SurrealQL ORDER BY fragment
applyLinkPrefix / stripLinkPrefix	Auto-prefixes record-link fields on write, strips on read
prepareCreate / normaliseReturnedId	Id strategy handlers: record-id (default), plain, ulid
applyBetterAuthSchema / BETTER_AUTH_SURREAL_SCHEMA	Bundled canonical 17-table SurrealQL schema
createInMemoryKeyStore	In-memory JWKS storage with rotation and expiration
BETTER_AUTH_SURREALDB_CODES + BetterAuthSurrealError	Structured error registry
instrument	OTel instrumentation wrapper for adapter operations
runAdapterConformance	Reusable conformance test harness

File Structure

packages/identity/auth/better-auth-surrealdb/src/
  adapter/            createBetterAuthSurrealAdapter, betterAuthSurrealAdapter (v1.6), internals, operations
  compile/            compileWhere, compileSelect, compileSortBy
  id-strategy/        prepareCreate, normaliseReturnedId, generateUlid
  link-fields/        applyLinkPrefix, stripLinkPrefix, DEFAULT_BETTER_AUTH_LINK_FIELDS
  schema/             BETTER_AUTH_SURREAL_SCHEMA, applyBetterAuthSchema
  schemas/            Zod schemas for options and link field maps
  error-codes/        BETTER_AUTH_SURREALDB_CODES and BetterAuthSurrealError
  otel/               instrument, AdapterOutcome, resetInstrumentsForTesting
  types/              TypeScript interfaces (BetterAuthSurrealAdapterOptions, Row, etc.)
  testing/            runAdapterConformance harness

Sibling packages

• @suaveplan/surrealdb — SurrealAdapter for database operations
• @suaveplan/testing-integration-surrealdb — SurrealDB container fixture for conformance tests
• @suaveplan/error — structured error registry via defineCodes
• @suaveplan/types — shared TypeScript primitives

Patterns

Quick Start (v1.6)

import { SurrealAdapter } from "@suaveplan/surrealdb";
import { applyBetterAuthSchema } from "@suaveplan/better-auth-surrealdb/schema";
import { betterAuthSurrealAdapter } from "@suaveplan/better-auth-surrealdb/adapter/v1.6";
import { betterAuth } from "better-auth";

const client = new SurrealAdapter({ url: "ws://localhost:8000", namespace: "auth", database: "auth", username: "root", password: process.env.SURREAL_PASSWORD });
await client.connect();
await applyBetterAuthSchema(client);

export const auth = betterAuth({
  database: betterAuthSurrealAdapter({ client }),
  secret: process.env.BETTER_AUTH_SECRET,
  baseURL: "http://localhost:3000",
  emailAndPassword: { enabled: true },
});

Direct adapter (v1.4 shape)

import { createBetterAuthSurrealAdapter } from "@suaveplan/better-auth-surrealdb/adapter";

const adapter = createBetterAuthSurrealAdapter({ client });
await adapter.create({ model: "user", data: { id: "u1", email: "a@b" } });

Custom link fields

createBetterAuthSurrealAdapter({
  client,
  linkFields: { session: { userId: "user" }, member: { userId: "user", organizationId: "tenant" } },
});

Constraints

• Peer dependency on better-auth ^1.4.0 (type-only at package boundary)
• SurrealDB v3 required (uses record<target> typed links)
• Default id strategy is record-id; rejects ids containing :
• Schema version moves in lockstep with package version
• Conformance harness requires Docker SurrealDB container

Checklist

• Verify adapter implements all 10 Better-Auth Adapter methods
• Confirm BETTER_AUTH_SURREALDB_CODES registered via defineCodes
• Check subpath exports in package.json align with src/ modules
• Run bunx turbo lint typecheck test build --filter=@suaveplan/better-auth-surrealdb
• Confirm conformance harness passes against SurrealDB container