Initial Commit

packages/identity/auth/better-auth-surrealdb/src/schema/schema.md

@@ -0,0 +1,75 @@
+# schema
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Bundles the canonical 17-table Better-Auth SurrealQL schema as a frozen
+string constant `BETTER_AUTH_SURREAL_SCHEMA` and exposes a one-shot
+`applyBetterAuthSchema(client)` helper for callers who do not run their
+DDL through `@suaveplan/api-migrations`. Schema content is mirrored
+byte-for-byte from the canonical source-of-truth file
+`/mnt/f/surrealdb/surql/features/02-auth/02-better-auth.surql`; future
+upstream changes require a coordinated package version bump.
+
+## Features
+
+- 17 DDL targets: `user` field extensions, plus `session`, `account`,
+  `verification`, `passkey`, `jwks`, `sso_provider`, `oauth_application`,
+  `oauth_access_token`, `oauth_consent`, `organization`, `member`,
+  `invitation`, `team`, `team_member`, `two_factor`, `api_key`.
+- 13 indexes (account provider, verification identifier, SSO provider id,
+  oauth client/access/refresh tokens, organization slug, passkey
+  credential, user phone, api_key prefix/user, member/team uniqueness,
+  invitation email/org).
+- Idempotent on re-application — every `DEFINE TABLE`/`DEFINE FIELD`/
+  `DEFINE INDEX` uses the `OVERWRITE` flag.
+- `applyBetterAuthSchema(client)` executes the schema via the
+  `SurrealClientView.execute()` surface and wraps any underlying failure
+  in `BetterAuthSurrealError(QUERY_FAILED)`.
+
+## Usage: Basic
+
+```ts
+import { SurrealAdapter } from "@suaveplan/surrealdb";
+import { applyBetterAuthSchema } from "@suaveplan/better-auth-surrealdb/schema";
+
+const client = new SurrealAdapter({ url: "ws://localhost:8000" });
+await client.connect();
+await applyBetterAuthSchema(client);
+```
+
+## Usage: Advanced
+
+```ts
+import { BETTER_AUTH_SURREAL_SCHEMA } from "@suaveplan/better-auth-surrealdb/schema";
+
+// Pipe the schema through @suaveplan/api-migrations
+import { createSurrealqlAdapter } from "@suaveplan/api-migrations";
+
+const migrations = createSurrealqlAdapter({
+    steps: [
+        { id: "001-better-auth", up: BETTER_AUTH_SURREAL_SCHEMA },
+    ],
+});
+
+await migrations.run(client);
+```
+
+## API Reference
+
+- `BETTER_AUTH_SURREAL_SCHEMA: string` — frozen DDL string.
+- `applyBetterAuthSchema(client: SurrealClientView): Promise<void>` — executes
+  the schema via `client.execute(...)`; wraps failures in `QUERY_FAILED`.
+
+## Implementation Notes
+
+The constant is a single string literal so bundlers can tree-shake it out
+of consumers that import only `applyBetterAuthSchema` from sibling
+modules. Newlines are preserved (`\n`) so EXPLAIN output and DB logs stay
+human-readable. The helper executes the whole DDL in one `execute()`
+call; SurrealDB v3 parses multi-statement scripts natively and runs them
+sequentially within a single response. Failure capture preserves the
+underlying `SurrealError` via `cause` for upstream telemetry.