@stackframe/stack 1.0.0

package/dist/lib/stack-app.d.ts

@@ -0,0 +1,172 @@
+import { OauthProviderConfigJson, ServerUserCustomizableJson, ServerUserJson } from "@stackframe/stack-shared";
+import { ClientProjectJson, UserCustomizableJson, UserJson, EmailConfigJson, DomainConfigJson } from "@stackframe/stack-shared/dist/interface/clientInterface";
+import { ReadonlyJson } from "../utils/types";
+import { EmailVerificationLinkErrorCode, PasswordResetLinkErrorCode, SignInErrorCode, SignUpErrorCode } from "@stackframe/stack-shared/dist/utils/types";
+export type TokenStoreOptions<HasTokenStore extends boolean = boolean> = HasTokenStore extends true ? "cookie" | "nextjs-cookie" | "memory" : HasTokenStore extends false ? null : TokenStoreOptions<true> | TokenStoreOptions<false>;
+export type HandlerUrls = {
+    handler: string;
+    signIn: string;
+    signUp: string;
+    signOut: string;
+    emailVerification: string;
+    passwordReset: string;
+    forgotPassword: string;
+    home: string;
+    userHome: string;
+    oauthCallback: string;
+};
+export type StackClientAppConstructorOptions<HasTokenStore extends boolean, ProjectId extends string> = {
+    baseUrl?: string;
+    projectId?: ProjectId;
+    publishableClientKey?: string;
+    urls?: Partial<HandlerUrls>;
+    tokenStore: TokenStoreOptions<HasTokenStore>;
+};
+export type StackServerAppConstructorOptions<HasTokenStore extends boolean, ProjectId extends string> = StackClientAppConstructorOptions<HasTokenStore, ProjectId> & {
+    secretServerKey?: string;
+};
+export type StackAdminAppConstructorOptions<HasTokenStore extends boolean, ProjectId extends string> = StackServerAppConstructorOptions<HasTokenStore, ProjectId> & {
+    superSecretAdminKey?: string;
+};
+export type StackClientAppJson<HasTokenStore extends boolean, ProjectId extends string> = StackClientAppConstructorOptions<HasTokenStore, ProjectId> & {
+    uniqueIdentifier: string;
+};
+export declare const stackAppInternalsSymbol: unique symbol;
+type Auth<T, C> = {
+    readonly accessToken: string | null;
+    readonly refreshToken: string | null;
+    update(this: T, user: Partial<C>): Promise<void>;
+    signOut(this: T, redirectUrl?: string): Promise<never>;
+};
+export type User = {
+    readonly projectId: string;
+    readonly id: string;
+    readonly displayName: string | null;
+    /**
+     * The user's email address.
+     *
+     * Note: This might NOT be unique across multiple users, so always use `id` for unique identification.
+     */
+    readonly primaryEmail: string | null;
+    readonly primaryEmailVerified: boolean;
+    readonly profileImageUrl: string | null;
+    readonly signedUpAt: Date;
+    readonly clientMetadata: ReadonlyJson;
+    toJson(this: CurrentUser): UserJson;
+};
+export type CurrentUser = Auth<User, UserCustomizableJson> & User;
+/**
+ * A user including sensitive fields that should only be used on the server, never sent to the client
+ * (such as sensitive information and serverMetadata).
+ */
+export type ServerUser = Omit<User, "toJson"> & {
+    readonly serverMetadata: ReadonlyJson;
+    /**
+     * Returns a new user object with the sensitive fields removed.
+     */
+    getClientUser(this: ServerUser): User;
+    toJson(this: ServerUser): ServerUserJson;
+    update(this: ServerUser, user: Partial<ServerUserCustomizableJson>): Promise<void>;
+    delete(this: ServerUser): Promise<void>;
+};
+export type CurrentServerUser = Auth<ServerUser, ServerUserCustomizableJson> & Omit<ServerUser, "getClientUser"> & {
+    getClientUser(this: CurrentServerUser): CurrentUser;
+};
+export type Project = Readonly<{
+    id: string;
+    displayName: string;
+    description?: string;
+    createdAt: Date;
+    userCount: number;
+    isProductionMode: boolean;
+    evaluatedConfig: {
+        id: string;
+        allowLocalhost: boolean;
+        oauthProviders: OauthProviderConfig[];
+        emailConfig?: EmailConfig;
+        domains: DomainConfig[];
+    };
+}>;
+export type EmailConfig = EmailConfigJson;
+export type DomainConfig = DomainConfigJson;
+export type OauthProviderConfig = OauthProviderConfigJson;
+export type GetUserOptions = {
+    or?: 'redirect' | 'throw';
+};
+type AsyncStoreProperty<Name extends string, Value> = {
+    [key in `get${Capitalize<Name>}`]: () => Promise<Value>;
+} & {
+    [key in `on${Capitalize<Name>}Change`]: (callback: (value: Value) => void) => void;
+} & {
+    [key in `use${Capitalize<Name>}`]: () => Value;
+};
+export type StackClientApp<HasTokenStore extends boolean, ProjectId extends string = string> = ({
+    readonly projectId: ProjectId;
+    readonly urls: Readonly<HandlerUrls>;
+    signInWithOauth(provider: string): Promise<void>;
+    signInWithCredential(options: {
+        email: string;
+        password: string;
+        redirectUrl?: string;
+    }): Promise<SignInErrorCode | undefined>;
+    signUpWithCredential(options: {
+        email: string;
+        password: string;
+        redirectUrl?: string;
+    }): Promise<SignUpErrorCode | undefined>;
+    callOauthCallback(options?: {
+        redirectUrl?: string;
+    }): Promise<void>;
+    sendForgotPasswordEmail(email: string): Promise<void>;
+    resetPassword(options: {
+        code: string;
+        password: string;
+    }): Promise<PasswordResetLinkErrorCode | undefined>;
+    verifyPasswordResetCode(code: string): Promise<PasswordResetLinkErrorCode | undefined>;
+    verifyEmail(code: string): Promise<EmailVerificationLinkErrorCode | undefined>;
+    [stackAppInternalsSymbol]: {
+        toClientJson(): Promise<StackClientAppJson<HasTokenStore, ProjectId>>;
+    };
+} & AsyncStoreProperty<"project", ClientProjectJson> & {
+    [K in `redirectTo${Capitalize<keyof HandlerUrls>}`]: () => Promise<never>;
+} & (HasTokenStore extends false ? {} : {
+    useUser(options: GetUserOptions & {
+        or: 'redirect';
+    }): CurrentUser;
+    useUser(options: GetUserOptions & {
+        or: 'throw';
+    }): CurrentUser;
+    useUser(options?: GetUserOptions): CurrentUser | null;
+    getUser(options: GetUserOptions & {
+        or: 'redirect';
+    }): Promise<CurrentUser>;
+    getUser(options: GetUserOptions & {
+        or: 'throw';
+    }): Promise<CurrentUser>;
+    getUser(options?: GetUserOptions): Promise<CurrentUser | null>;
+    onUserChange: AsyncStoreProperty<"user", CurrentUser | null>["onUserChange"];
+}) & (ProjectId extends "internal" ? {
+    listOwnedProjects(): Promise<Project[]>;
+    createProject(project: Pick<Project, "displayName" | "description">): Promise<Project>;
+} : {}));
+type StackClientAppConstructor = {
+    new <TokenStoreType extends string, HasTokenStore extends (TokenStoreType extends {} ? true : boolean), ProjectId extends string>(options: StackClientAppConstructorOptions<HasTokenStore, ProjectId>): StackClientApp<HasTokenStore, ProjectId>;
+    new (options: StackClientAppConstructorOptions<boolean, string>): StackClientApp<boolean, string>;
+    [stackAppInternalsSymbol]: {
+        fromClientJson<HasTokenStore extends boolean, ProjectId extends string>(json: StackClientAppJson<HasTokenStore, ProjectId>): StackClientApp<HasTokenStore, ProjectId>;
+    };
+};
+export declare const StackClientApp: StackClientAppConstructor;
+export type StackServerApp<HasTokenStore extends boolean, ProjectId extends string = string> = (StackClientApp<HasTokenStore, ProjectId> & AsyncStoreProperty<"serverUser", CurrentServerUser | null> & {});
+type StackServerAppConstructor = {
+    new <TokenStoreType extends string, HasTokenStore extends (TokenStoreType extends {} ? true : boolean), ProjectId extends string>(options: StackServerAppConstructorOptions<HasTokenStore, ProjectId>): StackServerApp<HasTokenStore, ProjectId>;
+    new (options: StackServerAppConstructorOptions<boolean, string>): StackServerApp<boolean, string>;
+};
+export declare const StackServerApp: StackServerAppConstructor;
+export type StackAdminApp<HasTokenStore extends boolean, ProjectId extends string = string> = (StackServerApp<HasTokenStore, ProjectId> & AsyncStoreProperty<"projectAdmin", Project>);
+type StackAdminAppConstructor = {
+    new <TokenStoreType extends string, HasTokenStore extends (TokenStoreType extends {} ? true : boolean), ProjectId extends string>(options: StackAdminAppConstructorOptions<HasTokenStore, ProjectId>): StackAdminApp<HasTokenStore, ProjectId>;
+    new (options: StackAdminAppConstructorOptions<boolean, string>): StackAdminApp<boolean, string>;
+};
+export declare const StackAdminApp: StackAdminAppConstructor;
+export {};