@agentuity/core 2.0.0 → 2.0.1

package/dist/services/auth/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Authentication service types.
+ *
+ * @module services/auth
+ */
+export type { AuthUser, AuthSession, AuthContext, AuthOrgContext, AuthApiKeyPermissions, AuthApiKeyContext, AuthMethod, AgentuityAuth, AuthOrgHelpers, AuthApiKeyHelpers, AuthInterface, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/services/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACX,QAAQ,EACR,WAAW,EACX,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,aAAa,GACb,MAAM,SAAS,CAAC"}

package/dist/services/auth/index.js

@@ -0,0 +1,7 @@
+/**
+ * Authentication service types.
+ *
+ * @module services/auth
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/services/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/services/auth/types.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Core authentication types for Agentuity.
+ *
+ * These types are defined in @agentuity/core to avoid circular dependencies
+ * and allow packages like @agentuity/runtime to use auth types without
+ * pulling in heavy dependencies like drizzle-orm.
+ *
+ * @module services/auth/types
+ */
+/**
+ * Canonical authenticated user type for Agentuity Auth.
+ *
+ * Common fields include:
+ * - `id` – Stable user identifier
+ * - `email` – Primary email address
+ * - `name` – Display name
+ * - `image` – Avatar URL (if configured)
+ * - `createdAt` / `updatedAt` – Timestamps
+ */
+export interface AuthUser {
+    id: string;
+    email: string;
+    name?: string | null;
+    image?: string | null;
+    createdAt?: Date | string;
+    updatedAt?: Date | string;
+}
+/**
+ * Auth session type with organization plugin fields.
+ */
+export interface AuthSession {
+    id: string;
+    userId: string;
+    expiresAt: Date | string;
+    /** Active organization ID from the organization plugin */
+    activeOrganizationId?: string;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+    createdAt?: Date | string;
+    updatedAt?: Date | string;
+}
+/**
+ * Auth context containing user, session, and org data.
+ * This is the full auth context available on AgentContext.auth and c.var.auth.
+ * Session may be null for API key authentication.
+ */
+export interface AuthContext<TUser = AuthUser, TSession = AuthSession | null> {
+    user: TUser;
+    session: TSession;
+    org: AuthOrgContext | null;
+}
+/**
+ * Organization context from the organization plugin.
+ */
+export interface AuthOrgContext {
+    /** Organization ID */
+    id: string;
+    /** Organization slug (URL-friendly identifier) */
+    slug?: string | null;
+    /** Organization display name */
+    name?: string | null;
+    /** Member's role in this organization (e.g., 'owner', 'admin', 'member') */
+    role?: string | null;
+    /** Member ID for this user in this organization */
+    memberId?: string | null;
+    /** Organization metadata (if enabled) */
+    metadata?: unknown;
+}
+/**
+ * API key permissions format.
+ * Maps resource names to arrays of allowed actions.
+ *
+ * @example
+ * ```typescript
+ * const permissions: AuthApiKeyPermissions = {
+ *   project: ['read', 'write'],
+ *   user: ['read'],
+ *   admin: ['*'], // wildcard - all actions
+ * };
+ * ```
+ */
+export interface AuthApiKeyPermissions {
+    [key: string]: string[];
+}
+/**
+ * API key context when request is authenticated via API key.
+ */
+export interface AuthApiKeyContext {
+    /** API key ID */
+    id: string;
+    /** Display name of the API key */
+    name?: string | null;
+    /** Permissions associated with this API key */
+    permissions: AuthApiKeyPermissions;
+    /** User ID the API key belongs to */
+    userId?: string | null;
+}
+/**
+ * Authentication method used for the current request.
+ */
+export type AuthMethod = 'session' | 'api-key' | 'bearer';
+/**
+ * Generic authentication interface exposed on Hono context.
+ *
+ * This type is intentionally provider-agnostic.
+ *
+ * @typeParam TUser - Domain user type (defaults to unknown for flexibility).
+ * @typeParam TRaw - Underlying auth context (defaults to unknown for flexibility).
+ */
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+    /** Get the authenticated user, throws if not authenticated */
+    getUser(): Promise<TUser>;
+    /** Get the raw JWT token */
+    getToken(): Promise<string | null>;
+    /** Raw provider-specific auth object or auth context */
+    raw: TRaw;
+}
+/**
+ * Organization helpers available on the auth context.
+ */
+export interface AuthOrgHelpers {
+    /** Active organization context if available, null otherwise */
+    org: AuthOrgContext | null;
+    /** Returns active org or null (never throws) */
+    getOrg(): Promise<AuthOrgContext | null>;
+    /** Convenience accessor for the member's role on the active org */
+    getOrgRole(): Promise<string | null>;
+    /** True if the current member's role is one of the provided roles */
+    hasOrgRole(...roles: string[]): Promise<boolean>;
+}
+/**
+ * API key helpers available on the auth context.
+ */
+export interface AuthApiKeyHelpers {
+    /** How this request was authenticated */
+    authMethod: AuthMethod;
+    /** API key context when request is authenticated via API key, null otherwise */
+    apiKey: AuthApiKeyContext | null;
+    /**
+     * Check if the API key has the required permissions.
+     * All specified actions must be present for the resource.
+     * Supports '*' wildcard which matches any action.
+     *
+     * @param resource - The resource to check (e.g., 'project', 'user')
+     * @param actions - Actions required (e.g., 'read', 'write')
+     * @returns true if all actions are permitted, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check for specific permission
+     * if (c.var.auth.hasPermission('project', 'write')) { ... }
+     *
+     * // Check for multiple permissions (all required)
+     * if (c.var.auth.hasPermission('project', 'read', 'write')) { ... }
+     * ```
+     */
+    hasPermission(resource: string, ...actions: string[]): boolean;
+}
+/**
+ * Full authentication interface available on `c.var.auth` and `ctx.auth`.
+ *
+ * This is the primary interface you'll use to access authentication data
+ * in your route handlers and agents. It provides:
+ *
+ * - User data via `getUser()`
+ * - Organization helpers via `getOrg()`, `getOrgRole()`, `hasOrgRole()`
+ * - API key helpers via `apiKey`, `hasPermission()`
+ * - Token access via `getToken()`
+ *
+ * @example Route handler
+ * ```typescript
+ * app.get('/api/profile', async (c) => {
+ *   const user = await c.var.auth.getUser();
+ *   const org = await c.var.auth.getOrg();
+ *   return c.json({ user, org });
+ * });
+ * ```
+ *
+ * @example Agent handler
+ * ```typescript
+ * handler: async (ctx, input) => {
+ *   if (!ctx.auth) return { error: 'Unauthorized' };
+ *   const user = await ctx.auth.getUser();
+ *   return { message: `Hello, ${user.email}!` };
+ * }
+ * ```
+ *
+ * @typeParam TUser - User type (extends AuthUser, defaults to AuthUser)
+ */
+export interface AuthInterface<TUser extends AuthUser = AuthUser> extends AgentuityAuth<TUser, AuthContext<TUser>>, AuthOrgHelpers, AuthApiKeyHelpers {
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/auth/types.ts"],"names":[],"mappings":"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"}

package/dist/services/auth/types.js

@@ -0,0 +1,11 @@
+/**
+ * Core authentication types for Agentuity.
+ *
+ * These types are defined in @agentuity/core to avoid circular dependencies
+ * and allow packages like @agentuity/runtime to use auth types without
+ * pulling in heavy dependencies like drizzle-orm.
+ *
+ * @module services/auth/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/services/index.d.ts

@@ -1,4 +1,5 @@
 export * from './adapter.ts';
+export * from './auth/index.ts';
 export * from './email/index.ts';
 export * from './exception.ts';
 export * from './keyvalue/index.ts';

package/dist/services/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/services/index.js

@@ -1,4 +1,5 @@
 export * from "./adapter.js";
+export * from "./auth/index.js";
 export * from "./email/index.js";
 export * from "./exception.js";
 export * from "./keyvalue/index.js";

package/dist/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAElC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AAEzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/core",
-	"version": "2.0.0",
+	"version": "2.0.1",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -89,7 +89,7 @@
 		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "2.0.0",
+		"@agentuity/test-utils": "2.0.1",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"esbuild": "^0.25.0",

package/src/services/auth/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Authentication service types.
+ *
+ * @module services/auth
+ */
+
+export type {
+	AuthUser,
+	AuthSession,
+	AuthContext,
+	AuthOrgContext,
+	AuthApiKeyPermissions,
+	AuthApiKeyContext,
+	AuthMethod,
+	AgentuityAuth,
+	AuthOrgHelpers,
+	AuthApiKeyHelpers,
+	AuthInterface,
+} from './types';

package/src/services/auth/types.ts

@@ -0,0 +1,223 @@
+/**
+ * Core authentication types for Agentuity.
+ *
+ * These types are defined in @agentuity/core to avoid circular dependencies
+ * and allow packages like @agentuity/runtime to use auth types without
+ * pulling in heavy dependencies like drizzle-orm.
+ *
+ * @module services/auth/types
+ */
+
+// =============================================================================
+// Canonical User/Session Types
+// =============================================================================
+
+/**
+ * Canonical authenticated user type for Agentuity Auth.
+ *
+ * Common fields include:
+ * - `id` – Stable user identifier
+ * - `email` – Primary email address
+ * - `name` – Display name
+ * - `image` – Avatar URL (if configured)
+ * - `createdAt` / `updatedAt` – Timestamps
+ */
+export interface AuthUser {
+	id: string;
+	email: string;
+	name?: string | null;
+	image?: string | null;
+	createdAt?: Date | string;
+	updatedAt?: Date | string;
+}
+
+/**
+ * Auth session type with organization plugin fields.
+ */
+export interface AuthSession {
+	id: string;
+	userId: string;
+	expiresAt: Date | string;
+	/** Active organization ID from the organization plugin */
+	activeOrganizationId?: string;
+	ipAddress?: string | null;
+	userAgent?: string | null;
+	createdAt?: Date | string;
+	updatedAt?: Date | string;
+}
+
+/**
+ * Auth context containing user, session, and org data.
+ * This is the full auth context available on AgentContext.auth and c.var.auth.
+ * Session may be null for API key authentication.
+ */
+export interface AuthContext<TUser = AuthUser, TSession = AuthSession | null> {
+	user: TUser;
+	session: TSession;
+	org: AuthOrgContext | null;
+}
+
+/**
+ * Organization context from the organization plugin.
+ */
+export interface AuthOrgContext {
+	/** Organization ID */
+	id: string;
+	/** Organization slug (URL-friendly identifier) */
+	slug?: string | null;
+	/** Organization display name */
+	name?: string | null;
+	/** Member's role in this organization (e.g., 'owner', 'admin', 'member') */
+	role?: string | null;
+	/** Member ID for this user in this organization */
+	memberId?: string | null;
+	/** Organization metadata (if enabled) */
+	metadata?: unknown;
+}
+
+// =============================================================================
+// API Key Types
+// =============================================================================
+
+/**
+ * API key permissions format.
+ * Maps resource names to arrays of allowed actions.
+ *
+ * @example
+ * ```typescript
+ * const permissions: AuthApiKeyPermissions = {
+ *   project: ['read', 'write'],
+ *   user: ['read'],
+ *   admin: ['*'], // wildcard - all actions
+ * };
+ * ```
+ */
+export interface AuthApiKeyPermissions {
+	[key: string]: string[];
+}
+
+/**
+ * API key context when request is authenticated via API key.
+ */
+export interface AuthApiKeyContext {
+	/** API key ID */
+	id: string;
+	/** Display name of the API key */
+	name?: string | null;
+	/** Permissions associated with this API key */
+	permissions: AuthApiKeyPermissions;
+	/** User ID the API key belongs to */
+	userId?: string | null;
+}
+
+/**
+ * Authentication method used for the current request.
+ */
+export type AuthMethod = 'session' | 'api-key' | 'bearer';
+
+// =============================================================================
+// Auth Interface
+// =============================================================================
+
+/**
+ * Generic authentication interface exposed on Hono context.
+ *
+ * This type is intentionally provider-agnostic.
+ *
+ * @typeParam TUser - Domain user type (defaults to unknown for flexibility).
+ * @typeParam TRaw - Underlying auth context (defaults to unknown for flexibility).
+ */
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+	/** Get the authenticated user, throws if not authenticated */
+	getUser(): Promise<TUser>;
+
+	/** Get the raw JWT token */
+	getToken(): Promise<string | null>;
+
+	/** Raw provider-specific auth object or auth context */
+	raw: TRaw;
+}
+
+/**
+ * Organization helpers available on the auth context.
+ */
+export interface AuthOrgHelpers {
+	/** Active organization context if available, null otherwise */
+	org: AuthOrgContext | null;
+
+	/** Returns active org or null (never throws) */
+	getOrg(): Promise<AuthOrgContext | null>;
+
+	/** Convenience accessor for the member's role on the active org */
+	getOrgRole(): Promise<string | null>;
+
+	/** True if the current member's role is one of the provided roles */
+	hasOrgRole(...roles: string[]): Promise<boolean>;
+}
+
+/**
+ * API key helpers available on the auth context.
+ */
+export interface AuthApiKeyHelpers {
+	/** How this request was authenticated */
+	authMethod: AuthMethod;
+
+	/** API key context when request is authenticated via API key, null otherwise */
+	apiKey: AuthApiKeyContext | null;
+
+	/**
+	 * Check if the API key has the required permissions.
+	 * All specified actions must be present for the resource.
+	 * Supports '*' wildcard which matches any action.
+	 *
+	 * @param resource - The resource to check (e.g., 'project', 'user')
+	 * @param actions - Actions required (e.g., 'read', 'write')
+	 * @returns true if all actions are permitted, false otherwise
+	 *
+	 * @example
+	 * ```typescript
+	 * // Check for specific permission
+	 * if (c.var.auth.hasPermission('project', 'write')) { ... }
+	 *
+	 * // Check for multiple permissions (all required)
+	 * if (c.var.auth.hasPermission('project', 'read', 'write')) { ... }
+	 * ```
+	 */
+	hasPermission(resource: string, ...actions: string[]): boolean;
+}
+
+/**
+ * Full authentication interface available on `c.var.auth` and `ctx.auth`.
+ *
+ * This is the primary interface you'll use to access authentication data
+ * in your route handlers and agents. It provides:
+ *
+ * - User data via `getUser()`
+ * - Organization helpers via `getOrg()`, `getOrgRole()`, `hasOrgRole()`
+ * - API key helpers via `apiKey`, `hasPermission()`
+ * - Token access via `getToken()`
+ *
+ * @example Route handler
+ * ```typescript
+ * app.get('/api/profile', async (c) => {
+ *   const user = await c.var.auth.getUser();
+ *   const org = await c.var.auth.getOrg();
+ *   return c.json({ user, org });
+ * });
+ * ```
+ *
+ * @example Agent handler
+ * ```typescript
+ * handler: async (ctx, input) => {
+ *   if (!ctx.auth) return { error: 'Unauthorized' };
+ *   const user = await ctx.auth.getUser();
+ *   return { message: `Hello, ${user.email}!` };
+ * }
+ * ```
+ *
+ * @typeParam TUser - User type (extends AuthUser, defaults to AuthUser)
+ */
+export interface AuthInterface<TUser extends AuthUser = AuthUser>
+	extends AgentuityAuth<TUser, AuthContext<TUser>>,
+		AuthOrgHelpers,
+		AuthApiKeyHelpers {}

package/src/services/index.ts

@@ -1,4 +1,5 @@
 export * from './adapter.ts';
+export * from './auth/index.ts';
 export * from './email/index.ts';
 export * from './exception.ts';
 export * from './keyvalue/index.ts';