@wemogy/better-auth-cosmos 0.0.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wemogy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,111 @@
 # @wemogy/better-auth-cosmos
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+`@wemogy/better-auth-cosmos` is a production-ready adapter that connects **better-auth** to Azure Cosmos DB. Containers are derived from the better-auth schema at runtime, so the core models and any active plugin models are provisioned automatically with query-optimized partition keys.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+Maintained by **wemogy**.
+
+## Contents
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Purpose
+## Features
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@wemogy/better-auth-cosmos`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+- Native integration with Azure Cosmos DB including automatic container naming
+- Containers derived from the better-auth schema: active plugins (including third-party ones) get their containers created automatically
+- Query-optimized partition keys per model (e.g. sessions by `/token`), overridable via `partitionKeys`
+- Parameterized Cosmos SQL queries
+- Optional debug logging to aid local development and acceptance testing
 
-## What is OIDC Trusted Publishing?
+## Requirements
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+- Node.js 20 or later
+- Access to an Azure Cosmos DB account with permission to manage databases and containers
+- better-auth ^1.3.33 or later
+- An existing better-auth configuration
 
-## Setup Instructions
+## Installation
 
-To properly configure OIDC trusted publishing for this package:
+Install the package using your package manager of choice:
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+```bash
+npm install @wemogy/better-auth-cosmos
+# or
+pnpm add @wemogy/better-auth-cosmos
+# or
+yarn add @wemogy/better-auth-cosmos
+```
 
-## DO NOT USE THIS PACKAGE
+## Quick Start
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```typescript
+import { betterAuth } from 'better-auth';
+import { buildCosmosAdapter } from '@wemogy/better-auth-cosmos';
 
-## More Information
+export const createAuth = async () => {
+  const cosmosAdapter = await buildCosmosAdapter({
+    adapterId: 'cosmos',
+    adapterName: 'Cosmos Adapter',
+    dbCredentials: {
+      endpoint: process.env.COSMOS_DB_ENDPOINT!,
+      key: process.env.COSMOS_DB_KEY!,
+    },
+    dbName: process.env.COSMOS_DB_NAME ?? 'better-auth',
+    debugLogs: process.env.NODE_ENV !== 'production',
+    usePlural: false,
+  });
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+  return betterAuth({
+    database: cosmosAdapter,
+  });
+};
+```
 
----
+### Environment variables
 
-**Maintained for OIDC setup purposes only**
+```bash
+COSMOS_DB_ENDPOINT="https://<your-account>.documents.azure.com:443/"
+COSMOS_DB_KEY="<secret>"
+COSMOS_DB_NAME="better-auth"
+```
+
+## Configuration
+
+`buildCosmosAdapter` accepts the following options:
+
+| Option          | Type                      | Default      | Description                                                                                     |
+| --------------- | ------------------------- | ------------ | ----------------------------------------------------------------------------------------------- |
+| `adapterId`     | `string`                  | **required** | Identifier used by better-auth to track the adapter instance.                                   |
+| `adapterName`   | `string`                  | **required** | Friendly name used in logs and debugging.                                                       |
+| `dbCredentials` | `CosmosClientOptions`     | **required** | Credentials and configuration passed to the underlying `CosmosClient` (e.g. `endpoint`, `key`). |
+| `dbName`        | `string`                  | **required** | Name of the Cosmos DB database where containers will be created.                                |
+| `debugLogs`     | `DBAdapterDebugLogOption` | `false`      | Enables verbose logging. Useful in development environments only.                               |
+| `usePlural`     | `boolean`                 | `false`      | Whether to pluralize container names (e.g. `users` instead of `user`).                          |
+| `partitionKeys` | `Record<string, string>`  | None         | Partition key path per model (e.g. `{ session: '/userId' }`), overriding the built-in defaults. |
+
+The database is created on startup; containers are created lazily from the better-auth schema when the adapter initializes, so only the models required by your active plugins are provisioned. Known models get optimized partition keys (`session` → `/token`, `verification` → `/identifier`, `account`/`twoFactor` → `/userId`, organization-scoped models → `/organizationId`); unknown plugin models default to `/id`. Note that partition keys are immutable on existing containers.
+
+## Troubleshooting
+
+- **Initialization fails with 401 Unauthorized:** Confirm that the configured `endpoint` and `key` belong to the same Cosmos DB account and that the key has data plane permissions.
+- **Missing collections:** Ensure the configured database exists and the account has unlimited container throughput or the necessary RU/s reserved.
+- **Debug logs missing:** Set `debugLogs: true` explicitly or run with `NODE_ENV=development`.
+
+## Contributing
+
+We welcome improvements and bug fixes. To contribute:
+
+1. Fork the repository and create a branch.
+2. Install dependencies with `pnpm install` from the root.
+3. Run the tests via `npm test` in the `packages/better-auth-cosmos` directory. For integration tests, provide a Cosmos DB instance.
+4. Submit a pull request describing your changes.
+
+## License
+
+UNLICENSED © wemogy

package/dist/cosmos.d.ts

@@ -0,0 +1,39 @@
+import { CosmosClientOptions, ItemDefinition, SqlQuerySpec } from '@azure/cosmos';
+export interface ContainerSpec {
+    name: string;
+    /**
+     * Partition key path, e.g. '/id' or '/userId'. Defaults to '/id'.
+     * Must be a single leading-slash segment.
+     */
+    partitionKey?: string;
+}
+export declare class Cosmos {
+    private client;
+    private database;
+    /**
+     * Partition key field per (final, possibly pluralized) container name.
+     * Needed for deletes, where the partition key value must be supplied explicitly.
+     */
+    private partitionKeyFields;
+    private ensuredContainers;
+    private constructor();
+    static create(credentials: CosmosClientOptions, dbName?: string, containers?: ContainerSpec[], usePlural?: boolean): Promise<Cosmos>;
+    private static pluralize;
+    private createContainers;
+    /**
+     * Create the given containers if they don't exist yet. Idempotent: each
+     * container is only created once per Cosmos instance. Names are expected
+     * to be final container names (custom model names / pluralization applied).
+     */
+    ensureContainers(containers: ContainerSpec[]): Promise<void>;
+    private ensureContainer;
+    private getContainer;
+    create<T extends ItemDefinition>(containerName: string, item: T): Promise<T & import("@azure/cosmos").Resource>;
+    update<T extends ItemDefinition>(containerName: string, item: T): Promise<ItemDefinition & import("@azure/cosmos").Resource>;
+    findOne<T extends ItemDefinition>(containerName: string, query: string | SqlQuerySpec): Promise<T | undefined>;
+    findMany<T extends ItemDefinition>(containerName: string, query: string | SqlQuerySpec): Promise<T[]>;
+    count(containerName: string, query: string | SqlQuerySpec): Promise<number>;
+    delete(containerName: string, item: ItemDefinition & {
+        id: string;
+    }): Promise<void>;
+}

package/dist/cosmos.js

@@ -0,0 +1,129 @@
+import { CosmosClient } from '@azure/cosmos';
+/**
+ * Derive the document field name from a partition key path, rejecting anything
+ * that is not a single leading-slash segment (e.g. `userId`, `/a/b`). Cosmos
+ * requires partition key paths to start with `/`, and the delete path needs a
+ * top-level field name — validating here turns those mistakes into an early,
+ * explicit error instead of a deferred container-creation failure or a silently
+ * mis-addressed delete.
+ */
+const partitionKeyFieldFromPath = (partitionKey) => {
+    if (!/^\/[^/]+$/.test(partitionKey)) {
+        throw new Error(`Invalid partition key path "${partitionKey}": expected a single leading-slash segment such as "/id" or "/userId".`);
+    }
+    return partitionKey.slice(1);
+};
+export class Cosmos {
+    client;
+    database;
+    /**
+     * Partition key field per (final, possibly pluralized) container name.
+     * Needed for deletes, where the partition key value must be supplied explicitly.
+     */
+    partitionKeyFields = {};
+    ensuredContainers = new Map();
+    constructor(credentials) {
+        this.client = new CosmosClient(credentials);
+    }
+    static async create(credentials, dbName, containers, usePlural) {
+        const instance = new Cosmos(credentials);
+        if (dbName) {
+            const { database } = await instance.client.databases.createIfNotExists({ id: dbName });
+            instance.database = database;
+        }
+        if (instance.database && containers) {
+            await instance.createContainers(containers, usePlural);
+        }
+        return instance;
+    }
+    static pluralize(word) {
+        if (word.endsWith('s') || word.endsWith('sh') || word.endsWith('ch') || word.endsWith('x') || word.endsWith('z')) {
+            return word + 'es';
+        }
+        if (word.endsWith('y') && !/[aeiou]y$/.test(word)) {
+            return word.slice(0, -1) + 'ies';
+        }
+        return word + 's';
+    }
+    async createContainers(containers, usePlural) {
+        await Promise.all(containers.map(({ name, partitionKey }) => {
+            const finalName = usePlural ? Cosmos.pluralize(name) : name;
+            return this.ensureContainer({ name: finalName, partitionKey });
+        }));
+    }
+    /**
+     * Create the given containers if they don't exist yet. Idempotent: each
+     * container is only created once per Cosmos instance. Names are expected
+     * to be final container names (custom model names / pluralization applied).
+     */
+    async ensureContainers(containers) {
+        await Promise.all(containers.map(container => this.ensureContainer(container)));
+    }
+    ensureContainer({ name, partitionKey = '/id' }) {
+        let pending = this.ensuredContainers.get(name);
+        if (!pending) {
+            // Validate the path up front so a bad config fails loudly here rather than
+            // as a deferred container-creation rejection.
+            this.partitionKeyFields[name] = partitionKeyFieldFromPath(partitionKey);
+            pending = this.database.containers.createIfNotExists({ id: name, partitionKey: { paths: [partitionKey] } }).catch(error => {
+                // Don't cache a failed creation: a transient error (throttling, network)
+                // would otherwise poison this container for the whole process lifetime.
+                // Drop the entry so a later operation can retry.
+                this.ensuredContainers.delete(name);
+                // eslint-disable-next-line no-console
+                console.error(`[better-auth-cosmos] Failed to create container "${name}":`, error);
+                throw error;
+            });
+            this.ensuredContainers.set(name, pending);
+        }
+        return pending;
+    }
+    getContainer(containerName) {
+        return this.database.container(containerName);
+    }
+    async create(containerName, item) {
+        const { resource } = await this.getContainer(containerName).items.create(item);
+        if (!resource) {
+            throw new Error(`Cosmos create returned no resource for container "${containerName}"`);
+        }
+        return resource;
+    }
+    async update(containerName, item) {
+        const { resource } = await this.getContainer(containerName).items.upsert(item);
+        if (!resource) {
+            throw new Error(`Cosmos upsert returned no resource for container "${containerName}"`);
+        }
+        return resource;
+    }
+    async findOne(containerName, query) {
+        const container = this.getContainer(containerName);
+        const { resources } = await container.items.query(query).fetchAll();
+        return resources[0];
+    }
+    async findMany(containerName, query) {
+        const container = this.getContainer(containerName);
+        const { resources } = await container.items.query(query).fetchAll();
+        return resources;
+    }
+    async count(containerName, query) {
+        const { resources } = await this.getContainer(containerName).items.query(query).fetchAll();
+        // `SELECT VALUE COUNT(1)` always yields exactly one row; an empty result
+        // means the query shape is wrong, which must not be reported as "0 matches".
+        if (resources.length === 0) {
+            throw new Error(`Count query returned no rows for container "${containerName}"`);
+        }
+        return resources[0];
+    }
+    async delete(containerName, item) {
+        const partitionKeyField = this.partitionKeyFields[containerName] ?? 'id';
+        const partitionKeyValue = item[partitionKeyField];
+        // Refuse to guess the partition value: substituting item.id when the real
+        // partition key field is absent would address the wrong logical partition.
+        if (partitionKeyValue === undefined || partitionKeyValue === null) {
+            throw new Error(`Document "${item.id}" in container "${containerName}" is missing partition key field "${partitionKeyField}"; refusing to delete to avoid targeting the wrong partition.`);
+        }
+        await this.getContainer(containerName)
+            .item(item.id, partitionKeyValue)
+            .delete();
+    }
+}

package/dist/cosmosAdapter.d.ts

@@ -0,0 +1,86 @@
+import { ItemDefinition } from '@azure/cosmos';
+import type { CleanedWhere, Where } from 'better-auth/adapters';
+import { Cosmos } from './cosmos';
+interface CosmosAdapterDeps {
+    cosmos: Cosmos;
+    getModelName: (model: string) => string;
+    getFieldName: (args: {
+        model: string;
+        field: string;
+    }) => string;
+    /**
+     * Allowed document field names per model, derived from the better-auth schema.
+     * Whitelists identifiers (where/sortBy/select) before they are interpolated
+     * into Cosmos SQL — Cosmos cannot parameterize identifiers, so an unvalidated
+     * field name would be a SQL injection vector.
+     */
+    validFields: Record<string, ReadonlySet<string>>;
+    /**
+     * Resolves once all containers required by the active better-auth schema exist.
+     */
+    ready: Promise<void>;
+}
+export declare class CosmosAdapter {
+    private readonly cosmos;
+    private readonly getModelName;
+    private readonly getFieldName;
+    private readonly validFields;
+    private readonly ready;
+    constructor({ cosmos, getModelName, getFieldName, validFields, ready }: CosmosAdapterDeps);
+    /**
+     * Reject any identifier that is not a known field of the model. better-auth's
+     * adapter factory already maps and validates `where` field names (and throws
+     * on unknown ones), so for `where` this is a second line of defense; for
+     * `sortBy` and `select` — which the factory does not validate — it is the
+     * primary guard against an unvalidated identifier reaching the query text.
+     */
+    private assertField;
+    private mapField;
+    private mapSelect;
+    private mapSortBy;
+    private assertWhere;
+    create<T extends ItemDefinition>({ model, data, select: _select }: {
+        model: string;
+        data: T;
+        select?: string[];
+    }): Promise<T & import("@azure/cosmos").Resource>;
+    update<T extends ItemDefinition>({ model, where, update }: {
+        model: string;
+        where: Required<Where>[];
+        update: T;
+    }): Promise<(ItemDefinition & import("@azure/cosmos").Resource) | null>;
+    updateMany<T extends ItemDefinition>({ model, where, update }: {
+        model: string;
+        where: CleanedWhere[];
+        update: T;
+    }): Promise<number>;
+    delete<T extends ItemDefinition>({ model, where }: {
+        model: string;
+        where?: CleanedWhere[];
+    }): Promise<void>;
+    deleteMany<T extends ItemDefinition>({ model, where }: {
+        model: string;
+        where?: CleanedWhere[];
+    }): Promise<number>;
+    findOne<T extends ItemDefinition>({ model, select, where }: {
+        model: string;
+        select?: string[];
+        where: CleanedWhere[];
+    }): Promise<T | undefined>;
+    findMany<T extends ItemDefinition>({ model, select, where, sortBy, offset, limit, }: {
+        model: string;
+        select?: string[];
+        where?: CleanedWhere[];
+        sortBy?: {
+            field: string;
+            direction: 'asc' | 'desc';
+        };
+        offset?: number;
+        limit?: number;
+    }): Promise<T[]>;
+    count({ model, where }: {
+        model: string;
+        where?: CleanedWhere[];
+    }): Promise<number>;
+}
+export {};

package/dist/cosmosAdapter.js

@@ -0,0 +1,113 @@
+import { queryBuilder } from './util/queryBuilder';
+export class CosmosAdapter {
+    cosmos;
+    getModelName;
+    getFieldName;
+    validFields;
+    ready;
+    constructor({ cosmos, getModelName, getFieldName, validFields, ready }) {
+        this.cosmos = cosmos;
+        this.getModelName = getModelName;
+        this.getFieldName = getFieldName;
+        this.validFields = validFields;
+        this.ready = ready;
+    }
+    /**
+     * Reject any identifier that is not a known field of the model. better-auth's
+     * adapter factory already maps and validates `where` field names (and throws
+     * on unknown ones), so for `where` this is a second line of defense; for
+     * `sortBy` and `select` — which the factory does not validate — it is the
+     * primary guard against an unvalidated identifier reaching the query text.
+     */
+    assertField(model, field) {
+        const allowed = this.validFields[model];
+        if (allowed && !allowed.has(field)) {
+            throw new Error(`Unknown field "${field}" for model "${model}"`);
+        }
+    }
+    // `select` and `sortBy` arrive with logical field names (the factory does not
+    // transform them), so map them to the physical document property names and
+    // validate the result before it reaches the query.
+    mapField(model, field) {
+        const mapped = this.getFieldName({ model, field });
+        this.assertField(model, mapped);
+        return mapped;
+    }
+    mapSelect(model, select) {
+        return select?.map(field => this.mapField(model, field));
+    }
+    mapSortBy(model, sortBy) {
+        if (!sortBy) {
+            return undefined;
+        }
+        return { ...sortBy, field: this.mapField(model, sortBy.field) };
+    }
+    // `where` field names arrive already mapped to physical column names by the
+    // factory; validate them as defense in depth before they reach the query.
+    assertWhere(model, where) {
+        where?.forEach(({ field }) => {
+            this.assertField(model, field);
+        });
+    }
+    async create({ model, data, select: _select }) {
+        void _select;
+        await this.ready;
+        return await this.cosmos.create(this.getModelName(model), data);
+    }
+    async update({ model, where, update }) {
+        if (!where?.length) {
+            return null;
+        }
+        this.assertWhere(model, where);
+        await this.ready;
+        const existingItem = await this.cosmos.findOne(this.getModelName(model), queryBuilder({ where }));
+        if (!existingItem) {
+            return null;
+        }
+        const updatedItem = { ...existingItem, ...update };
+        return await this.cosmos.update(this.getModelName(model), updatedItem);
+    }
+    async updateMany({ model, where, update }) {
+        this.assertWhere(model, where);
+        await this.ready;
+        const existingItems = await this.cosmos.findMany(this.getModelName(model), queryBuilder({ where }));
+        const updated = await Promise.all(existingItems.map(item => {
+            const updatedItem = { ...(item || {}), ...update };
+            return this.cosmos.update(this.getModelName(model), updatedItem);
+        }));
+        return updated.length;
+    }
+    async delete({ model, where }) {
+        this.assertWhere(model, where);
+        await this.ready;
+        const existingItem = await this.cosmos.findOne(this.getModelName(model), queryBuilder({ where }));
+        if (existingItem?.id) {
+            await this.cosmos.delete(this.getModelName(model), existingItem);
+        }
+    }
+    async deleteMany({ model, where }) {
+        this.assertWhere(model, where);
+        await this.ready;
+        const existingItems = await this.cosmos.findMany(this.getModelName(model), queryBuilder({ where }));
+        const deleted = await Promise.all(existingItems.filter(item => item.id).map(item => this.cosmos.delete(this.getModelName(model), item)));
+        return deleted.length;
+    }
+    async findOne({ model, select, where }) {
+        this.assertWhere(model, where);
+        const mappedSelect = this.mapSelect(model, select);
+        await this.ready;
+        return await this.cosmos.findOne(this.getModelName(model), queryBuilder({ select: mappedSelect, where }));
+    }
+    async findMany({ model, select, where, sortBy, offset, limit, }) {
+        this.assertWhere(model, where);
+        const mappedSelect = this.mapSelect(model, select);
+        const mappedSortBy = this.mapSortBy(model, sortBy);
+        await this.ready;
+        return await this.cosmos.findMany(this.getModelName(model), queryBuilder({ select: mappedSelect, where, sortBy: mappedSortBy, offset, limit }));
+    }
+    async count({ model, where }) {
+        this.assertWhere(model, where);
+        await this.ready;
+        return await this.cosmos.count(this.getModelName(model), queryBuilder({ where, countOnly: true }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+import { CosmosClientOptions } from '@azure/cosmos';
+import type { BetterAuthOptions } from 'better-auth';
+import { type AdapterFactory, type DBAdapterDebugLogOption } from 'better-auth/adapters';
+import { CosmosAdapter } from './cosmosAdapter';
+export { CosmosAdapter };
+interface CosmosAdapterConfig {
+    /**
+     * A unique identifier for the adapter.
+     */
+    adapterId: string;
+    /**
+     * The name of the adapter.
+     */
+    adapterName: string;
+    /**
+     * Helps you debug issues with the adapter.
+     */
+    debugLogs?: DBAdapterDebugLogOption;
+    /**
+     * If the table names in the schema are plural.
+     */
+    usePlural?: boolean;
+    /**
+     * Cosmos DB credentials
+     */
+    dbCredentials: CosmosClientOptions;
+    /**
+     * Database name
+     */
+    dbName: string;
+    /**
+     * Partition key path per model (e.g. `{ session: '/userId' }`).
+     * Overrides the built-in defaults, which are chosen to match
+     * Better Auth's hottest lookup per container.
+     */
+    partitionKeys?: Record<string, string>;
+}
+export declare const buildCosmosAdapter: (config: CosmosAdapterConfig) => Promise<AdapterFactory<BetterAuthOptions>>;

package/dist/index.js

@@ -0,0 +1,70 @@
+import { createAdapterFactory } from 'better-auth/adapters';
+import { Cosmos } from './cosmos';
+import { CosmosAdapter } from './cosmosAdapter';
+export { CosmosAdapter };
+/**
+ * Default partition key per container, aligned with the most frequent
+ * Better Auth query against it (session by token on every request,
+ * verification by identifier, account/twoFactor by userId, org-scoped
+ * models by organizationId, ...). Falls back to '/id'.
+ */
+const defaultPartitionKeys = {
+    user: '/id',
+    session: '/token',
+    verification: '/identifier',
+    account: '/userId',
+    organization: '/id',
+    member: '/organizationId',
+    team: '/organizationId',
+    invitation: '/organizationId',
+    teamMember: '/teamId',
+    twoFactor: '/userId',
+};
+export const buildCosmosAdapter = async (config) => {
+    const { adapterId, adapterName, dbCredentials, dbName, debugLogs = false, usePlural = false, partitionKeys } = config;
+    const cosmos = await Cosmos.create(dbCredentials, dbName);
+    return createAdapterFactory({
+        config: {
+            adapterId,
+            adapterName,
+            usePlural,
+            debugLogs,
+            supportsJSON: true,
+            supportsDates: false,
+            supportsBooleans: true,
+            supportsNumericIds: false,
+        },
+        adapter: ({ options: _options, schema, debugLog, getModelName, getFieldName, getFieldAttributes }) => {
+            // Mark parameters as intentionally unused to match Better Auth adapter signature
+            void _options;
+            void debugLog;
+            void getFieldAttributes;
+            // Derive containers from the schema, which contains exactly the models
+            // required by the active better-auth plugins (including third-party ones).
+            const containers = Object.keys(schema).map(model => ({
+                name: getModelName(model),
+                partitionKey: partitionKeys?.[model] ?? defaultPartitionKeys[model] ?? '/id',
+            }));
+            const ready = cosmos.ensureContainers(containers);
+            // The same `ready` promise is awaited in every adapter operation, so a
+            // container-creation failure resurfaces there. This handler runs on a
+            // detached chain purely to (a) avoid an unhandled-rejection warning and
+            // (b) log the failure so it is visible even if no operation runs yet.
+            ready.catch(error => {
+                // eslint-disable-next-line no-console
+                console.error('[better-auth-cosmos] Cosmos container provisioning failed:', error);
+            });
+            // Whitelist of physical field names per model, used to reject unknown
+            // identifiers before they are interpolated into Cosmos SQL.
+            const validFields = {};
+            for (const [model, definition] of Object.entries(schema)) {
+                const fields = new Set(['id']);
+                for (const field of Object.keys(definition.fields)) {
+                    fields.add(getFieldName({ model, field }));
+                }
+                validFields[model] = fields;
+            }
+            return new CosmosAdapter({ cosmos, getModelName, getFieldName, validFields, ready });
+        },
+    });
+};

package/dist/models/account.d.ts

@@ -0,0 +1,14 @@
+export interface Account {
+    id: string;
+    userId: string;
+    accountId: string;
+    providerId: string;
+    accessToken?: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpiresAt?: Date;
+    refreshTokenExpiresAt?: Date;
+    scope?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/models/account.js

@@ -0,0 +1 @@
+export {};

package/dist/models/invitation.d.ts

@@ -0,0 +1,10 @@
+export interface Invitation {
+    id: string;
+    email: string;
+    inviterId: string;
+    organizationId: string;
+    role: string;
+    status: string;
+    expiresAt: Date;
+    teamId?: string;
+}

package/dist/models/invitation.js

@@ -0,0 +1 @@
+export {};

package/dist/models/member.d.ts

@@ -0,0 +1,8 @@
+export interface Member {
+    id: string;
+    userId: string;
+    organizationId: string;
+    role: string;
+    createdAt: Date;
+    updatedAt?: Date;
+}

package/dist/models/member.js

@@ -0,0 +1 @@
+export {};

package/dist/models/organization.d.ts

@@ -0,0 +1,9 @@
+export interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt?: Date;
+}

package/dist/models/organization.js

@@ -0,0 +1 @@
+export {};

package/dist/models/session.d.ts

@@ -0,0 +1,12 @@
+export interface Session {
+    id: string;
+    userId: string;
+    expiresAt: Date;
+    token: string;
+    ipAddress?: string;
+    userAgent?: string;
+    activeOrganizationId?: string;
+    activeTeamId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/models/session.js

@@ -0,0 +1 @@
+export {};

package/dist/models/team.d.ts

@@ -0,0 +1,7 @@
+export interface Team {
+    id: string;
+    name: string;
+    organizationId: string;
+    createdAt: Date;
+    updatedAt?: Date;
+}

package/dist/models/team.js

@@ -0,0 +1 @@
+export {};

package/dist/models/teamMember.d.ts

@@ -0,0 +1,6 @@
+export interface TeamMember {
+    id: string;
+    teamId: string;
+    userId: string;
+    createdAt: Date;
+}

package/dist/models/teamMember.js

@@ -0,0 +1 @@
+export {};

package/dist/models/twoFactor.d.ts

@@ -0,0 +1,6 @@
+export interface TwoFactor {
+    id: string;
+    userId: string;
+    secret?: string;
+    backupCodes?: string;
+}

package/dist/models/twoFactor.js

@@ -0,0 +1 @@
+export {};

package/dist/models/user.d.ts

@@ -0,0 +1,10 @@
+export interface User {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    emailVerified: boolean;
+    twoFactorEnabled?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/models/user.js

@@ -0,0 +1 @@
+export {};

package/dist/models/verificationToken.d.ts

@@ -0,0 +1,7 @@
+export interface VerificationToken {
+    id: string;
+    identifier: string;
+    token: string;
+    expiresAt: Date;
+    createdAt: Date;
+}

package/dist/models/verificationToken.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,93 @@
+export interface CustomAdapterConfig {
+    debugLogs?: boolean;
+    usePlural?: boolean;
+}
+export interface User {
+    id: string;
+    email: string;
+    name?: string;
+    image?: string;
+    emailVerified: boolean;
+    twoFactorEnabled?: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Session {
+    id: string;
+    userId: string;
+    expiresAt: Date;
+    token: string;
+    ipAddress?: string;
+    userAgent?: string;
+    activeOrganizationId?: string;
+    activeTeamId?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Account {
+    id: string;
+    userId: string;
+    accountId: string;
+    providerId: string;
+    accessToken?: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpiresAt?: Date;
+    refreshTokenExpiresAt?: Date;
+    scope?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface VerificationToken {
+    id: string;
+    identifier: string;
+    token: string;
+    expiresAt: Date;
+    createdAt: Date;
+}
+export interface Organization {
+    id: string;
+    name: string;
+    slug: string;
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface Member {
+    id: string;
+    userId: string;
+    organizationId: string;
+    role: string;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface Invitation {
+    id: string;
+    email: string;
+    inviterId: string;
+    organizationId: string;
+    role: string;
+    status: string;
+    expiresAt: Date;
+    teamId?: string;
+}
+export interface Team {
+    id: string;
+    name: string;
+    organizationId: string;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface TeamMember {
+    id: string;
+    teamId: string;
+    userId: string;
+    createdAt: Date;
+}
+export interface TwoFactor {
+    id: string;
+    userId: string;
+    secret?: string;
+    backupCodes?: string;
+}

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/util/queryBuilder.d.ts

@@ -0,0 +1,18 @@
+import type { SqlQuerySpec } from '@azure/cosmos';
+import type { CleanedWhere } from 'better-auth/adapters';
+interface QueryBuilderOptions {
+    select?: string[];
+    where?: CleanedWhere[];
+    sortBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    offset?: number;
+    limit?: number;
+    /**
+     * Build a `SELECT VALUE COUNT(1)` query instead of returning documents.
+     */
+    countOnly?: boolean;
+}
+export declare const queryBuilder: ({ select, where, sortBy, offset, limit, countOnly }: QueryBuilderOptions) => SqlQuerySpec;
+export {};

package/dist/util/queryBuilder.js

@@ -0,0 +1,99 @@
+export const queryBuilder = ({ select = ['*'], where, sortBy, offset, limit, countOnly }) => {
+    const parameters = [];
+    const addParameter = (value) => {
+        const name = `@p${parameters.length}`;
+        parameters.push({ name, value: value });
+        return name;
+    };
+    // Group conditions by connector the same way better-auth's reference adapters
+    // do: AND-connector conditions form one group, OR-connector conditions another,
+    // and the two groups are AND-ed together — i.e. `(a AND b) AND (c OR d)`.
+    // Parentheses are only emitted when both groups are present, so the SQL is
+    // unambiguous for mixed connectors without changing the all-AND / all-OR shape.
+    const andConditions = [];
+    const orConditions = [];
+    for (const w of where ?? []) {
+        (w.connector === 'OR' ? orConditions : andConditions).push(mapCondition(w, addParameter));
+    }
+    const andClause = andConditions.join(' AND ');
+    const orClause = orConditions.join(' OR ');
+    let whereClause = '';
+    if (andConditions.length && orConditions.length) {
+        whereClause = `(${andClause}) AND (${orClause})`;
+    }
+    else {
+        whereClause = andClause || orClause;
+    }
+    const columns = select.length === 1 && select.at(0) === '*' ? '*' : select.map(column => `c.${column}`).join(', ');
+    let query = `SELECT ${countOnly ? 'VALUE COUNT(1)' : columns} FROM c${whereClause ? ` WHERE ${whereClause}` : ''}${sortBy ? ` ORDER BY c.${sortBy.field} ${sortBy.direction}` : ''}`;
+    // Handle pagination
+    // offset/limit are interpolated into the query text (Cosmos has no parameter
+    // binding for these), so they must be validated as non-negative integers.
+    const safeOffset = offset === undefined ? undefined : assertNonNegativeInteger(offset, 'offset');
+    const safeLimit = limit === undefined ? undefined : assertNonNegativeInteger(limit, 'limit');
+    // If limit is provided, always include OFFSET (default 0) and LIMIT
+    // If only offset is provided, include OFFSET and LIMIT 0
+    if (safeLimit !== undefined) {
+        query += ` OFFSET ${safeOffset ?? 0} LIMIT ${safeLimit}`;
+    }
+    else if (safeOffset !== undefined && safeOffset > 0) {
+        query += ` OFFSET ${safeOffset} LIMIT 0`;
+    }
+    return { query: query.trim(), parameters };
+};
+const assertNonNegativeInteger = (value, name) => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`Invalid ${name}: expected a non-negative integer, received ${value}`);
+    }
+    return value;
+};
+const mapCondition = (where, addParameter) => {
+    if (where.operator === 'contains') {
+        return `CONTAINS(c.${where.field}, ${addParameter(where.value)}, true)`;
+    }
+    if (where.operator === 'starts_with') {
+        return `STARTSWITH(c.${where.field}, ${addParameter(where.value)}, true)`;
+    }
+    if (where.operator === 'ends_with') {
+        return `ENDSWITH(c.${where.field}, ${addParameter(where.value)}, true)`;
+    }
+    if (where.operator === 'in' && Array.isArray(where.value)) {
+        return `ARRAY_CONTAINS(${addParameter(where.value)}, c.${where.field})`;
+    }
+    if (where.operator === 'not_in' && Array.isArray(where.value)) {
+        return `NOT ARRAY_CONTAINS(${addParameter(where.value)}, c.${where.field})`;
+    }
+    // Comparing against null with `=` / `!=` yields undefined in Cosmos SQL,
+    // so null checks need the IS_NULL builtin instead.
+    if (where.value === null) {
+        if (where.operator === 'ne') {
+            return `NOT IS_NULL(c.${where.field})`;
+        }
+        return `IS_NULL(c.${where.field})`;
+    }
+    let mappedOperator;
+    switch (where.operator) {
+        case 'eq':
+            mappedOperator = '=';
+            break;
+        case 'ne':
+            mappedOperator = '!=';
+            break;
+        case 'lt':
+            mappedOperator = '<';
+            break;
+        case 'lte':
+            mappedOperator = '<=';
+            break;
+        case 'gt':
+            mappedOperator = '>';
+            break;
+        case 'gte':
+            mappedOperator = '>=';
+            break;
+        default:
+            mappedOperator = '=';
+            break;
+    }
+    return `c.${where.field} ${mappedOperator} ${addParameter(where.value)}`;
+};

package/package.json

@@ -1,10 +1,61 @@
 {
   "name": "@wemogy/better-auth-cosmos",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @wemogy/better-auth-cosmos",
+  "version": "1.0.1",
+  "description": "A custom better-auth adapter that integrates with Azure Cosmos DB.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wemogy/better-auth.git",
+    "directory": "packages/better-auth-cosmos"
+  },
+  "homepage": "https://github.com/wemogy/better-auth/wiki",
+  "bugs": {
+    "url": "https://github.com/wemogy/better-auth/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@azure/cosmos": "^4.7.0"
+  },
+  "peerDependencies": {
+    "better-auth": "^1.3.34"
+  },
+  "devDependencies": {
+    "@better-auth/test-utils": "^1.6.17",
+    "@eslint/js": "^9.38.0",
+    "@types/node": "^24.9.1",
+    "better-auth": "^1.3.34",
+    "eslint": "^9.38.0",
+    "eslint-plugin-check-file": "^3.3.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-react-naming-convention": "^2.2.4",
+    "globals": "^16.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "vite": "^6.4.2",
+    "vitest": "^3.2.6"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "better-auth",
+    "cosmosdb",
+    "adapter"
+  ],
+  "author": "wemogy IT",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --w",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "check": "prettier --check \"src/**/*.ts\" && eslint src/**/*.ts"
+  }
+}