@stackframe/stack-shared 2.4.14 → 2.4.21

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @stackframe/stack-shared
 
+## 2.4.21
+
+### Patch Changes
+
+- Bugfixes
+- Updated dependencies
+  - @stackframe/stack-sc@2.4.21
+
+## 2.4.20
+
+### Patch Changes
+
+- Support multiple projects on the same domain
+- Updated dependencies
+  - @stackframe/stack-sc@2.4.20
+
+## 2.4.19
+
+### Patch Changes
+
+- Sync package versions
+- Updated dependencies
+  - @stackframe/stack-sc@2.4.19
+
 ## 2.4.14
 
 ### Patch Changes

package/dist/interface/adminInterface.d.ts

@@ -1,10 +1,10 @@
 import { ServerAuthApplicationOptions, StackServerInterface } from "./serverInterface";
 import { EmailConfigJson, ProjectJson, SharedProvider, StandardProvider } from "./clientInterface";
-import { Session } from "../sessions";
+import { InternalSession } from "../sessions";
 export type AdminAuthApplicationOptions = Readonly<ServerAuthApplicationOptions & ({
     superSecretAdminKey: string;
 } | {
-    projectOwnerSession: Session;
+    projectOwnerSession: InternalSession;
 })>;
 export type OAuthProviderUpdateOptions = {
     id: string;
@@ -67,7 +67,7 @@ export type ApiKeySetCreateOptions = {
 export declare class StackAdminInterface extends StackServerInterface {
     readonly options: AdminAuthApplicationOptions;
     constructor(options: AdminAuthApplicationOptions);
-    protected sendAdminRequest(path: string, options: RequestInit, session: Session | null, requestType?: "admin"): Promise<Response & {
+    protected sendAdminRequest(path: string, options: RequestInit, session: InternalSession | null, requestType?: "admin"): Promise<Response & {
         usedTokens: {
             accessToken: import("../sessions").AccessToken;
             refreshToken: import("../sessions").RefreshToken | null;
@@ -80,5 +80,5 @@ export declare class StackAdminInterface extends StackServerInterface {
     createApiKeySet(options: ApiKeySetCreateOptions): Promise<ApiKeySetFirstViewJson>;
     listApiKeySets(): Promise<ApiKeySetJson[]>;
     revokeApiKeySetById(id: string): Promise<void>;
-    getApiKeySet(id: string, session: Session): Promise<ApiKeySetJson>;
+    getApiKeySet(id: string, session: InternalSession): Promise<ApiKeySetJson>;
 }

package/dist/interface/clientInterface.d.ts

@@ -2,7 +2,7 @@ import { Result } from "../utils/results";
 import { ReadonlyJson } from '../utils/json';
 import { KnownErrors } from '../known-errors';
 import { ProjectUpdateOptions } from './adminInterface';
-import { AccessToken, RefreshToken, Session } from '../sessions';
+import { AccessToken, RefreshToken, InternalSession } from '../sessions';
 type UserCustomizableJson = {
     displayName: string | null;
     clientMetadata: ReadonlyJson;
@@ -43,7 +43,7 @@ export type ClientInterfaceOptions = {
 } & ({
     publishableClientKey: string;
 } | {
-    projectOwnerSession: Session;
+    projectOwnerSession: InternalSession;
 });
 export type SharedProvider = "shared-github" | "shared-google" | "shared-facebook" | "shared-microsoft" | "shared-spotify";
 export declare const sharedProviders: readonly ["shared-github", "shared-google", "shared-facebook", "shared-microsoft", "shared-spotify"];
@@ -129,14 +129,14 @@ export declare class StackClientInterface {
     get projectId(): string;
     getApiUrl(): string;
     fetchNewAccessToken(refreshToken: RefreshToken): Promise<AccessToken | null>;
-    protected sendClientRequest(path: string, requestOptions: RequestInit, session: Session | null, requestType?: "client" | "server" | "admin"): Promise<Response & {
+    protected sendClientRequest(path: string, requestOptions: RequestInit, session: InternalSession | null, requestType?: "client" | "server" | "admin"): Promise<Response & {
         usedTokens: {
             accessToken: AccessToken;
             refreshToken: RefreshToken | null;
         } | null;
     }>;
-    createSession(options: Omit<ConstructorParameters<typeof Session>[0], "refreshAccessTokenCallback">): Session;
-    protected sendClientRequestAndCatchKnownError<E extends typeof KnownErrors[keyof KnownErrors]>(path: string, requestOptions: RequestInit, tokenStoreOrNull: Session | null, errorsToCatch: readonly E[]): Promise<Result<Response & {
+    createSession(options: Omit<ConstructorParameters<typeof InternalSession>[0], "refreshAccessTokenCallback">): InternalSession;
+    protected sendClientRequestAndCatchKnownError<E extends typeof KnownErrors[keyof KnownErrors]>(path: string, requestOptions: RequestInit, tokenStoreOrNull: InternalSession | null, errorsToCatch: readonly E[]): Promise<Result<Response & {
         usedTokens: {
             accessToken: AccessToken;
             refreshToken: RefreshToken | null;
@@ -145,7 +145,7 @@ export declare class StackClientInterface {
     private sendClientRequestInner;
     private _processResponse;
     sendForgotPasswordEmail(email: string, redirectUrl: string): Promise<KnownErrors["UserNotFound"] | undefined>;
-    sendVerificationEmail(emailVerificationRedirectUrl: string, session: Session): Promise<KnownErrors["EmailAlreadyVerified"] | undefined>;
+    sendVerificationEmail(emailVerificationRedirectUrl: string, session: InternalSession): Promise<KnownErrors["EmailAlreadyVerified"] | undefined>;
     sendMagicLinkEmail(email: string, redirectUrl: string): Promise<KnownErrors["RedirectUrlNotWhitelisted"] | undefined>;
     resetPassword(options: {
         code: string;
@@ -157,18 +157,18 @@ export declare class StackClientInterface {
     updatePassword(options: {
         oldPassword: string;
         newPassword: string;
-    }, session: Session): Promise<KnownErrors["PasswordMismatch"] | KnownErrors["PasswordRequirementsNotMet"] | undefined>;
+    }, session: InternalSession): Promise<KnownErrors["PasswordMismatch"] | KnownErrors["PasswordRequirementsNotMet"] | undefined>;
     verifyPasswordResetCode(code: string): Promise<KnownErrors["PasswordResetCodeError"] | undefined>;
     verifyEmail(code: string): Promise<KnownErrors["EmailVerificationError"] | undefined>;
-    signInWithCredential(email: string, password: string, session: Session): Promise<KnownErrors["EmailPasswordMismatch"] | {
+    signInWithCredential(email: string, password: string, session: InternalSession): Promise<KnownErrors["EmailPasswordMismatch"] | {
         accessToken: string;
         refreshToken: string;
     }>;
-    signUpWithCredential(email: string, password: string, emailVerificationRedirectUrl: string, session: Session): Promise<KnownErrors["UserEmailAlreadyExists"] | KnownErrors["PasswordRequirementsNotMet"] | {
+    signUpWithCredential(email: string, password: string, emailVerificationRedirectUrl: string, session: InternalSession): Promise<KnownErrors["UserEmailAlreadyExists"] | KnownErrors["PasswordRequirementsNotMet"] | {
         accessToken: string;
         refreshToken: string;
     }>;
-    signInWithMagicLink(code: string, session: Session): Promise<KnownErrors["MagicLinkError"] | {
+    signInWithMagicLink(code: string, session: InternalSession): Promise<KnownErrors["MagicLinkError"] | {
         newUser: boolean;
         accessToken: string;
         refreshToken: string;
@@ -179,20 +179,20 @@ export declare class StackClientInterface {
         accessToken: string;
         refreshToken: string;
     }>;
-    signOut(session: Session): Promise<void>;
-    getClientUserByToken(tokenStore: Session): Promise<Result<UserJson>>;
+    signOut(session: InternalSession): Promise<void>;
+    getClientUserByToken(tokenStore: InternalSession): Promise<Result<UserJson>>;
     listClientUserTeamPermissions(options: {
         teamId: string;
         type: 'global' | 'team';
         direct: boolean;
-    }, session: Session): Promise<PermissionDefinitionJson[]>;
-    listClientUserTeams(session: Session): Promise<TeamJson[]>;
+    }, session: InternalSession): Promise<PermissionDefinitionJson[]>;
+    listClientUserTeams(session: InternalSession): Promise<TeamJson[]>;
     getClientProject(): Promise<Result<ClientProjectJson>>;
-    setClientUserCustomizableData(update: UserUpdateJson, session: Session): Promise<void>;
-    listProjects(session: Session): Promise<ProjectJson[]>;
+    setClientUserCustomizableData(update: UserUpdateJson, session: InternalSession): Promise<void>;
+    listProjects(session: InternalSession): Promise<ProjectJson[]>;
     createProject(project: ProjectUpdateOptions & {
         displayName: string;
-    }, session: Session): Promise<ProjectJson>;
+    }, session: InternalSession): Promise<ProjectJson>;
 }
 export declare function getProductionModeErrors(project: ProjectJson): ProductionModeError[];
 export {};

package/dist/interface/clientInterface.js

@@ -4,7 +4,7 @@ import { KnownError, KnownErrors } from '../known-errors';
 import { StackAssertionError, captureError, throwErr } from '../utils/errors';
 import { cookies } from '@stackframe/stack-sc';
 import { generateSecureRandomString } from '../utils/crypto';
-import { AccessToken, Session } from '../sessions';
+import { AccessToken, InternalSession } from '../sessions';
 import { globalVar } from '../utils/globals';
 export const sharedProviders = [
     "shared-github",
@@ -88,7 +88,7 @@ export class StackClientInterface {
         return await Result.orThrowAsync(Result.retry(() => this.sendClientRequestInner(path, requestOptions, session, requestType), 5, { exponentialDelayBase: 1000 }));
     }
     createSession(options) {
-        const session = new Session({
+        const session = new InternalSession({
             refreshAccessTokenCallback: async (refreshToken) => await this.fetchNewAccessToken(refreshToken),
             ...options,
         });
@@ -466,7 +466,7 @@ export class StackClientInterface {
                 await res.json();
             }
         }
-        session.invalidate();
+        session.markInvalid();
     }
     async getClientUserByToken(tokenStore) {
         const response = await this.sendClientRequest("/current-user", {}, tokenStore);

package/dist/interface/serverInterface.d.ts

@@ -2,7 +2,7 @@ import { ClientInterfaceOptions, UserJson, StackClientInterface, OrglikeJson, Us
 import { Result } from "../utils/results";
 import { ReadonlyJson } from "../utils/json";
 import { EmailTemplateCrud, ListEmailTemplatesCrud } from "./crud/email-templates";
-import { Session } from "../sessions";
+import { InternalSession } from "../sessions";
 export type ServerUserJson = UserJson & {
     serverMetadata: ReadonlyJson;
 };
@@ -29,27 +29,27 @@ export type ServerPermissionDefinitionJson = PermissionDefinitionJson & ServerPe
 export type ServerAuthApplicationOptions = (ClientInterfaceOptions & ({
     readonly secretServerKey: string;
 } | {
-    readonly projectOwnerSession: Session;
+    readonly projectOwnerSession: InternalSession;
 }));
 export declare const emailTemplateTypes: readonly ["EMAIL_VERIFICATION", "PASSWORD_RESET", "MAGIC_LINK"];
 export type EmailTemplateType = typeof emailTemplateTypes[number];
 export declare class StackServerInterface extends StackClientInterface {
     options: ServerAuthApplicationOptions;
     constructor(options: ServerAuthApplicationOptions);
-    protected sendServerRequest(path: string, options: RequestInit, session: Session | null, requestType?: "server" | "admin"): Promise<Response & {
+    protected sendServerRequest(path: string, options: RequestInit, session: InternalSession | null, requestType?: "server" | "admin"): Promise<Response & {
         usedTokens: {
             accessToken: import("../sessions").AccessToken;
             refreshToken: import("../sessions").RefreshToken | null;
         } | null;
     }>;
-    getServerUserByToken(session: Session): Promise<Result<ServerUserJson>>;
+    getServerUserByToken(session: InternalSession): Promise<Result<ServerUserJson>>;
     getServerUserById(userId: string): Promise<Result<ServerUserJson>>;
     listServerUserTeamPermissions(options: {
         teamId: string;
         type: 'global' | 'team';
         direct: boolean;
-    }, session: Session): Promise<ServerPermissionDefinitionJson[]>;
-    listServerUserTeams(session: Session): Promise<ServerTeamJson[]>;
+    }, session: InternalSession): Promise<ServerPermissionDefinitionJson[]>;
+    listServerUserTeams(session: InternalSession): Promise<ServerTeamJson[]>;
     listPermissionDefinitions(): Promise<ServerPermissionDefinitionJson[]>;
     createPermissionDefinition(data: ServerPermissionDefinitionCustomizableJson): Promise<ServerPermissionDefinitionJson>;
     updatePermissionDefinition(permissionId: string, data: Partial<ServerPermissionDefinitionCustomizableJson>): Promise<void>;

package/dist/sessions.d.ts

@@ -7,18 +7,18 @@ export declare class RefreshToken {
     constructor(token: string);
 }
 /**
- * A session represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
+ * An InternalSession represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
  *
- * A session never changes which user or session it belongs to, but the tokens may change over time.
+ * A session never changes which user or session it belongs to, but the tokens in it may change over time.
  */
-export declare class Session {
+export declare class InternalSession {
     private readonly _options;
     /**
     * Each session has a session key that depends on the tokens inside. If the session has a refresh token, the session key depends only on the refresh token. If the session does not have a refresh token, the session key depends only on the access token.
     *
     * Multiple Session objects may have the same session key, which implies that they represent the same session by the same user. Furthermore, a session's key never changes over the lifetime of a session object.
     *
-    * This makes session keys useful for caching and indexing sessions.
+    * This is useful for caching and indexing sessions.
     */
     readonly sessionKey: string;
     /**
@@ -42,15 +42,34 @@ export declare class Session {
         refreshToken: string | null;
         accessToken?: string | null;
     }): string;
-    invalidate(): void;
+    /**
+     * Marks the session object as invalid, meaning that the refresh and access tokens can no longer be used.
+     */
+    markInvalid(): void;
     onInvalidate(callback: () => void): {
         unsubscribe: () => void;
     };
+    /**
+     * Returns the access token if it is found in the cache, fetching it otherwise.
+     *
+     * This is usually the function you want to call to get an access token. When using the access token, you should catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
+     *
+     * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
+     */
     getPotentiallyExpiredTokens(): Promise<{
         accessToken: AccessToken;
         refreshToken: RefreshToken | null;
     } | null>;
-    getNewlyFetchedTokens(): Promise<{
+    /**
+     * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.
+     *
+     * The newly generated tokens are shortlived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
+     *
+     * In most cases, you should prefer `getPotentiallyExpiredTokens` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
+     *
+     * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).
+     */
+    fetchNewTokens(): Promise<{
         accessToken: AccessToken;
         refreshToken: RefreshToken | null;
     } | null>;

package/dist/sessions.js

@@ -12,18 +12,18 @@ export class RefreshToken {
     }
 }
 /**
- * A session represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
+ * An InternalSession represents a user's session, which may or may not be valid. It may contain an access token, a refresh token, or both.
  *
- * A session never changes which user or session it belongs to, but the tokens may change over time.
+ * A session never changes which user or session it belongs to, but the tokens in it may change over time.
  */
-export class Session {
+export class InternalSession {
     _options;
     /**
     * Each session has a session key that depends on the tokens inside. If the session has a refresh token, the session key depends only on the refresh token. If the session does not have a refresh token, the session key depends only on the access token.
     *
     * Multiple Session objects may have the same session key, which implies that they represent the same session by the same user. Furthermore, a session's key never changes over the lifetime of a session object.
     *
-    * This makes session keys useful for caching and indexing sessions.
+    * This is useful for caching and indexing sessions.
     */
     sessionKey;
     /**
@@ -42,7 +42,7 @@ export class Session {
         this._options = _options;
         this._accessToken = new Store(_options.accessToken ? new AccessToken(_options.accessToken) : null);
         this._refreshToken = _options.refreshToken ? new RefreshToken(_options.refreshToken) : null;
-        this.sessionKey = Session.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });
+        this.sessionKey = InternalSession.calculateSessionKey({ accessToken: _options.accessToken ?? null, refreshToken: _options.refreshToken });
     }
     static calculateSessionKey(ofTokens) {
         if (ofTokens.refreshToken) {
@@ -55,18 +55,37 @@ export class Session {
             return "not-logged-in";
         }
     }
-    invalidate() {
+    /**
+     * Marks the session object as invalid, meaning that the refresh and access tokens can no longer be used.
+     */
+    markInvalid() {
         this._accessToken.set(null);
         this._knownToBeInvalid.set(true);
     }
     onInvalidate(callback) {
         return this._knownToBeInvalid.onChange(() => callback());
     }
+    /**
+     * Returns the access token if it is found in the cache, fetching it otherwise.
+     *
+     * This is usually the function you want to call to get an access token. When using the access token, you should catch errors that occur if it expires, and call `markAccessTokenExpired` to mark the token as expired if so (after which a call to this function will always refetch the token).
+     *
+     * @returns null if the session is known to be invalid, cached tokens if they exist in the cache (which may or may not be valid still), or new tokens otherwise.
+     */
     async getPotentiallyExpiredTokens() {
         const accessToken = await this._getPotentiallyExpiredAccessToken();
         return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
     }
-    async getNewlyFetchedTokens() {
+    /**
+     * Fetches new tokens that are, at the time of fetching, guaranteed to be valid.
+     *
+     * The newly generated tokens are shortlived, so it's good practice not to rely on their validity (if possible). However, this function is useful in some cases where you only want to pass access tokens to a service, and you want to make sure said access token has the longest possible lifetime.
+     *
+     * In most cases, you should prefer `getPotentiallyExpiredTokens` with a fallback to `markAccessTokenExpired` and a retry mechanism if the endpoint rejects the token.
+     *
+     * @returns null if the session is known to be invalid, or new tokens otherwise (which, at the time of fetching, are guaranteed to be valid).
+     */
+    async fetchNewTokens() {
         const accessToken = await this._getNewlyFetchedAccessToken();
         return accessToken ? { accessToken, refreshToken: this._refreshToken } : null;
     }
@@ -117,7 +136,7 @@ export class Session {
                 this._refreshPromise = null;
                 this._accessToken.set(accessToken);
                 if (!accessToken) {
-                    this.invalidate();
+                    this.markInvalid();
                 }
             }
             return accessToken;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.4.14",
+  "version": "2.4.21",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -26,7 +26,7 @@
     "jose": "^5.2.2",
     "oauth4webapi": "^2.10.3",
     "uuid": "^9.0.1",
-    "@stackframe/stack-sc": "1.5.6"
+    "@stackframe/stack-sc": "2.4.21"
   },
   "devDependencies": {
     "rimraf": "^5.0.5",