@withstudiocms/sdk 0.0.0-beta.0 → 0.1.0-beta.1

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

@@ -0,0 +1,463 @@
+import { Effect } from '@withstudiocms/effect';
+import { type DBCallbackFailure } from '@withstudiocms/kysely';
+import type { DatabaseError } from '@withstudiocms/kysely/core/errors';
+import { DBClientLive, SDKDefaults } from '../../context.js';
+import { type AuthDeletionResponse } from '../../types.js';
+/**
+ * SDKAuthModule
+ *
+ * High-level authentication/data-access module implemented as an Effect generator.
+ * Returns a collection of sub-modules for working with email verification tokens,
+ * OAuth accounts, permissions, sessions and users. Each operation is implemented
+ * as composable Effect-driven functions that perform database operations, validate
+ * inputs/outputs with codecs/encoders and return typed database entities or
+ * domain-level results.
+ *
+ * Key characteristics
+ * - Built on top of an Effect system: most exported operations are Effects or
+ *   Effect.fn wrappers and should be run within the surrounding Effect runtime.
+ * - Uses runtime codecs/encoders to validate and parse inputs/outputs when
+ *   interacting with the database; DB rows returned conform to the project's
+ *   table schemas (e.g., StudioCMSUsersTable.Select, StudioCMSSessionTable.Select).
+ * - Encapsulates direct Kysely-style DB queries behind safe, validated call-sites.
+ * - Contains helper flows for common workflows (e.g., generate + insert verification
+ *   token, create user + permission, ensure ghost user exists).
+ *
+ * Returned sub-modules and notable behaviors
+ * - verifyEmail
+ *   - get(id: string): Effect that returns a verification token record or undefined.
+ *   - create(userId: string): Effect that generates a token, deletes any existing
+ *     token for the user and inserts a new token with an expiry (default 24h).
+ *   - delete(userId: string): Effect that deletes tokens for userId.
+ *
+ * - oAuth
+ *   - create(input): Effect that inserts a new OAuth account record.
+ *   - delete({ userId, provider }): Effect that attempts to delete an OAuth account
+ *     and returns a simple result object: { status: 'success'|'error', message: string }.
+ *     The delete flow maps common DB error tags (e.g., DBCallbackFailure, NotFoundError,
+ *     QueryError, QueryParseError) to meaningful status/message responses.
+ *   - searchByProviderId(input): Effect that finds an OAuth account by providerUserId + userId.
+ *
+ * - permission
+ *   - currentStatus(userId: string): Effect that returns the current permission row for a user
+ *     or undefined if none exists.
+ *
+ * - session
+ *   - create(sessionData): Effect that inserts a new session row and returns the created record.
+ *   - getById(id: string): Effect that returns a session row or undefined.
+ *   - sessionWithUser(sessionId: string): Effect that returns { session, user } or undefined
+ *     if either the session or user does not exist.
+ *   - delete(sessionId: string): Effect that deletes a session and returns a
+ *     { status, message } result similar to oAuth.delete; common DB failures are mapped to
+ *     friendly messages.
+ *   - update({ id, newDate }): Effect that updates a session's expiresAt and returns the
+ *     updated session record.
+ *
+ * - user
+ *   - create(userData, rank): Composed Effect that creates a new user and then creates
+ *     the corresponding permission record for the supplied rank.
+ *   - update({ userId, userData }): Effect that updates user fields and returns the updated user.
+ *   - searchUsersForUsernameOrEmail(username?, email?): Effect that searches by username and/or email
+ *     and returns both result arrays ({ usernameSearch, emailSearch }).
+ *   - ghost
+ *     - verifyExists(): Effect<boolean> that returns true if the configured ghost user exists.
+ *     - create(): Effect that creates the ghost user if missing and returns the ghost user row.
+ *     - get(): Effect that returns the ghost user row, creating it if necessary.
+ *
+ * Errors and failure modes
+ * - Most DB operations will propagate DB-level failures as Effect errors that the caller
+ *   can handle or map. Certain "delete" operations intentionally catch DB error tags and
+ *   convert them to structured success/error result objects for convenience.
+ * - Insert/update operations use returningAll() and executeTakeFirstOrThrow(), so failed
+ *   inserts/updates typically surface as runtime/DB errors within the Effect system.
+ *
+ * Usage notes
+ * - All exported operations are intended to be composed and executed inside the project's
+ *   Effect runtime. Consumers should use the project's Effect helpers to run or map results.
+ * - The module relies on configured DB client, token generator and default values (e.g.,
+ *   ghost user defaults). Ensure proper environment wiring before invoking these functions.
+ *
+ * Example (pseudocode)
+ * const auth = yield* SDKAuthModule;
+ * // create a user and permission
+ * const newUser = yield* auth.user.create(userInsertPayload, 'admin');
+ * // create and retrieve a session
+ * const session = yield* auth.session.create(sessionPayload);
+ * // create an email verification token
+ * const token = yield* auth.verifyEmail.create(newUser.id);
+ */
+export declare const SDKAuthModule: Effect.Effect<{
+    verifyEmail: {
+        /**
+         * Retrieves an email verification token by its ID.
+         *
+         * @param id - The ID of the email verification token to retrieve.
+         * @returns A promise that resolves to the email verification token if found, otherwise undefined.
+         */
+        get: (input: string) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly token: string;
+            readonly expiresAt: Date;
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Creates a new email verification token in the database.
+         *
+         * @param userId - The ID of the user to create the token for.
+         * @returns A promise that resolves to the created email verification token.
+         */
+        create: (userId: string) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly token: string;
+            readonly expiresAt: Date;
+        }, DBCallbackFailure | DatabaseError | import("../util/generators.js").GeneratorError, never>;
+        /**
+         * Deletes an email verification token from the database.
+         *
+         * @param userId - The ID of the user associated with the token.
+         * @returns A promise that resolves to the deletion response.
+         */
+        delete: (input: string) => Effect.Effect<import("kysely").DeleteResult, DBCallbackFailure | DatabaseError, never>;
+    };
+    oAuth: {
+        /**
+         * Creates a new OAuth account in the database.
+         *
+         * @param input - The OAuth account data to create.
+         * @returns A promise that resolves to the created OAuth account.
+         */
+        create: (input: {
+            readonly providerUserId: string;
+            readonly provider: string;
+            readonly userId: string;
+        }) => Effect.Effect<{
+            readonly providerUserId: string;
+            readonly provider: string;
+            readonly userId: string;
+        }, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Deletes an OAuth user account from the database.
+         *
+         * @param input - An object containing the userId and provider of the OAuth account to delete.
+         * @returns A promise that resolves to a status and message indicating the result of the deletion.
+         */
+        delete: (input: {
+            readonly userId: string;
+            readonly provider: string;
+        }) => AuthDeletionResponse;
+        /**
+         * Searches for an OAuth account by provider user ID and user ID.
+         *
+         * @param input - An object containing the providerUserId and userId to search for.
+         * @returns A promise that resolves to the found OAuth account if it exists, otherwise undefined.
+         */
+        searchByProviderId: (input: {
+            readonly providerUserId: string;
+            readonly userId: string;
+        }) => Effect.Effect<{
+            readonly providerUserId: string;
+            readonly provider: string;
+            readonly userId: string;
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Searches for OAuth providers for a given user ID.
+         *
+         * @param input - An object containing the providerId and userId to search for.
+         * @returns A promise that resolves to the found OAuth account if it exists, otherwise undefined.
+         */
+        searchProvidersForId: (input: {
+            readonly userId: string;
+            readonly providerId: string;
+        }) => Effect.Effect<{
+            readonly providerUserId: string;
+            readonly provider: string;
+            readonly userId: string;
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+    };
+    permission: {
+        /**
+         * Retrieves the current permission for a user by their ID.
+         *
+         * @param id - The ID of the user whose permission is to be retrieved.
+         * @returns A promise that resolves to the user's permission if found, otherwise undefined.
+         */
+        currentStatus: (input: string) => Effect.Effect<{
+            readonly user: string;
+            readonly rank: "owner" | "admin" | "editor" | "visitor" | "unknown";
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+    };
+    session: {
+        /**
+         * Creates a new session for a user.
+         *
+         * @param data - The session data to create.
+         * @returns A promise that resolves to the created session.
+         */
+        create: (input: {
+            readonly id: string;
+            readonly userId: string;
+            readonly expiresAt: string;
+        }) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly expiresAt: Date;
+        }, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Retrieves a user's Session by its ID.
+         *
+         * @param id - The ID of the session to retrieve.
+         * @returns A promise that resolves to the session if found, otherwise undefined.
+         */
+        getById: (input: string) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly expiresAt: Date;
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Retrieves a session along with its associated user by session ID.
+         *
+         * @param sessionId - The ID of the session to retrieve.
+         * @returns A promise that resolves to an object containing the session and user if found, otherwise undefined.
+         */
+        sessionWithUser: (sessionId: string) => Effect.Effect<{
+            session: {
+                readonly id: string;
+                readonly userId: string;
+                readonly expiresAt: Date;
+            };
+            user: {
+                readonly name: string;
+                readonly id: string;
+                readonly url: string | null | undefined;
+                readonly email: string | null | undefined;
+                readonly avatar: string | null | undefined;
+                readonly username: string;
+                readonly password: string | null | undefined;
+                readonly updatedAt: Date;
+                readonly createdAt: Date;
+                readonly emailVerified: boolean;
+                readonly notifications: string | null | undefined;
+            };
+        } | undefined, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Deletes a session by its ID.
+         *
+         * @param input - The ID of the session to delete.
+         * @returns A promise that resolves to a status and message indicating the result of the deletion.
+         */
+        delete: (input: string) => AuthDeletionResponse;
+        /**
+         * Updates a session's expiration date.
+         *
+         * @param input - An object containing the session ID and the new expiration date.
+         * @returns A promise that resolves to the updated session.
+         */
+        update: (input: {
+            readonly id: string;
+            readonly newDate: {
+                toString: {};
+                toDateString: {};
+                toTimeString: {};
+                toLocaleString: {};
+                toLocaleDateString: {};
+                toLocaleTimeString: {};
+                valueOf: {};
+                getTime: {};
+                getFullYear: {};
+                getUTCFullYear: {};
+                getMonth: {};
+                getUTCMonth: {};
+                getDate: {};
+                getUTCDate: {};
+                getDay: {};
+                getUTCDay: {};
+                getHours: {};
+                getUTCHours: {};
+                getMinutes: {};
+                getUTCMinutes: {};
+                getSeconds: {};
+                getUTCSeconds: {};
+                getMilliseconds: {};
+                getUTCMilliseconds: {};
+                getTimezoneOffset: {};
+                setTime: {};
+                setMilliseconds: {};
+                setUTCMilliseconds: {};
+                setSeconds: {};
+                setUTCSeconds: {};
+                setMinutes: {};
+                setUTCMinutes: {};
+                setHours: {};
+                setUTCHours: {};
+                setDate: {};
+                setUTCDate: {};
+                setMonth: {};
+                setUTCMonth: {};
+                setFullYear: {};
+                setUTCFullYear: {};
+                toUTCString: {};
+                toISOString: {};
+                toJSON: {};
+                getVarDate: {};
+                [Symbol.toPrimitive]: {};
+            };
+        }) => Effect.Effect<{
+            readonly id: string;
+            readonly userId: string;
+            readonly expiresAt: Date;
+        }, DBCallbackFailure | DatabaseError, never>;
+    };
+    user: {
+        /**
+         * Creates a new user with the specified permissions.
+         *
+         * @param userData - The data for the new user.
+         * @param rank - The permission rank for the new user.
+         * @returns A promise that resolves to the created user.
+         */
+        create: (userData: {
+            readonly name: string;
+            readonly id: string;
+            readonly url: string | null | undefined;
+            readonly email: string | null | undefined;
+            readonly avatar: string | null | undefined;
+            readonly username: string;
+            readonly password: string | null | undefined;
+            readonly updatedAt: string;
+            readonly createdAt: string | undefined;
+            readonly emailVerified: boolean;
+            readonly notifications: string | null | undefined;
+        }, rank: "owner" | "admin" | "editor" | "visitor" | "unknown") => Effect.Effect<{
+            readonly name: string;
+            readonly id: string;
+            readonly url: string | null | undefined;
+            readonly email: string | null | undefined;
+            readonly avatar: string | null | undefined;
+            readonly username: string;
+            readonly password: string | null | undefined;
+            readonly updatedAt: Date;
+            readonly createdAt: Date;
+            readonly emailVerified: boolean;
+            readonly notifications: string | null | undefined;
+        }, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Updates user data for a specified user.
+         *
+         * @param input - An object containing the userId and the userData to update.
+         * @returns A promise that resolves to the updated user.
+         */
+        update: (input: {
+            readonly userId: string;
+            readonly userData: {
+                readonly url?: string | null | undefined;
+                readonly email?: string | null | undefined;
+                readonly avatar?: string | null | undefined;
+                readonly password?: string | null | undefined;
+                readonly notifications?: string | null | undefined;
+                readonly name: string;
+                readonly id: string;
+                readonly username: string;
+                readonly updatedAt: string;
+                readonly emailVerified: boolean;
+            };
+        }) => Effect.Effect<{
+            readonly name: string;
+            readonly id: string;
+            readonly url: string | null | undefined;
+            readonly email: string | null | undefined;
+            readonly avatar: string | null | undefined;
+            readonly username: string;
+            readonly password: string | null | undefined;
+            readonly updatedAt: Date;
+            readonly createdAt: Date;
+            readonly emailVerified: boolean;
+            readonly notifications: string | null | undefined;
+        }, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Searches for users by username.
+         *
+         * @param username - The username to search for.
+         * @param email - The email to search for.
+         * @returns A promise that resolves to an array of users matching the username.
+         */
+        searchUsersForUsernameOrEmail: (username?: string | undefined, email?: string | undefined) => Effect.Effect<{
+            usernameSearch: {
+                readonly name: string;
+                readonly id: string;
+                readonly url: string | null | undefined;
+                readonly email: string | null | undefined;
+                readonly avatar: string | null | undefined;
+                readonly username: string;
+                readonly password: string | null | undefined;
+                readonly updatedAt: Date;
+                readonly createdAt: Date;
+                readonly emailVerified: boolean;
+                readonly notifications: string | null | undefined;
+            }[];
+            emailSearch: {
+                readonly name: string;
+                readonly id: string;
+                readonly url: string | null | undefined;
+                readonly email: string | null | undefined;
+                readonly avatar: string | null | undefined;
+                readonly username: string;
+                readonly password: string | null | undefined;
+                readonly updatedAt: Date;
+                readonly createdAt: Date;
+                readonly emailVerified: boolean;
+                readonly notifications: string | null | undefined;
+            }[];
+        }, DBCallbackFailure | DatabaseError, never>;
+        /**
+         * Verifies the existence of the ghost user.
+         *
+         * @returns A promise that resolves to true if the ghost user exists, otherwise false.
+         */
+        ghost: {
+            /**
+             * Verifies the existence of the ghost user.
+             *
+             * @returns A promise that resolves to true if the ghost user exists, otherwise false.
+             */
+            verifyExists: () => Effect.Effect<boolean, DBCallbackFailure | DatabaseError, never>;
+            /**
+             * Creates the ghost user if it does not already exist.
+             *
+             * @returns A promise that resolves to the ghost user.
+             */
+            create: () => Effect.Effect<{
+                readonly name: string;
+                readonly id: string;
+                readonly url: string | null | undefined;
+                readonly email: string | null | undefined;
+                readonly avatar: string | null | undefined;
+                readonly username: string;
+                readonly password: string | null | undefined;
+                readonly updatedAt: Date;
+                readonly createdAt: Date;
+                readonly emailVerified: boolean;
+                readonly notifications: string | null | undefined;
+            }, DBCallbackFailure | DatabaseError, never>;
+            /**
+             * Retrieves the ghost user.
+             *
+             * @returns A promise that resolves to the ghost user.
+             */
+            get: () => Effect.Effect<{
+                readonly name: string;
+                readonly id: string;
+                readonly url: string | null | undefined;
+                readonly email: string | null | undefined;
+                readonly avatar: string | null | undefined;
+                readonly username: string;
+                readonly password: string | null | undefined;
+                readonly updatedAt: Date;
+                readonly createdAt: Date;
+                readonly emailVerified: boolean;
+                readonly notifications: string | null | undefined;
+            }, DBCallbackFailure | DatabaseError, never>;
+        };
+    };
+}, import("effect/ConfigError").ConfigError, DBClientLive | SDKDefaults>;
+export default SDKAuthModule;